uv工具零基础完整教程

uv工具零基础完整教程

uv工具零基础完整讲解：是什么、有什么用、全套实操命令

适配所有Python项目，和Ruff同源一体化工具，零基础从安装到项目完整流程一步一步演示

目录

  1. 一、uv是什么？开发厂商与核心定位
  2. 二、原生pip/venv痛点 vs uv核心优势
  3. 三、跨平台一键安装uv
  4. 四、锁定项目Python版本 uv python pin
  5. 五、创建隔离虚拟环境 uv venv
  6. 六、安装/卸载项目依赖 uv add / remove
  7. 七、区分运行依赖与开发依赖 –dev
  8. 八、无需手动激活：uv run 运行代码/工具
  9. 九、多人协作统一环境 uv sync
  10. 十、高频辅助查询命令大全
  11. 十一、完整新项目标准操作流程

一、uv是什么？开发厂商与核心定位

零基础大白话解释

uv是Astral公司使用Rust语言开发的Python一体化环境管理工具，和代码规范工具Ruff出自同一团队，是2026年现代Python项目工业标准工具。

过去写Python程序，需要分开使用pip装包、venv创建虚拟环境、手动维护requirements.txt、手动激活环境运行脚本，命令零散、容易出现版本冲突、下载缓慢。

uv把Python版本锁定、虚拟环境、依赖安装卸载、项目配置管理、脚本运行全部整合为一套统一命令，速度比原生pip快数十至百倍，全程跨Windows/Mac/Linux命令完全一致。

适用场景：AI代码助手、后端服务、打包桌面exe、开源项目统一环境管理。

二、原生pip/venv痛点 vs uv核心优势

原生pip+venv 传统痛点

  • 依赖下载、解析速度极慢，大型项目等待很久
  • 虚拟环境创建、激活命令复杂，新手极易遗忘
  • 无法区分开发工具和线上运行依赖，打包冗余
  • 多设备协作时依赖版本不一致，本地能跑别人报错
  • 需要手动维护依赖清单文件，容易漏写包
  • 每次运行代码前必须手动激活venv，忘记就全局包冲突

uv 核心优势

  • Rust底层高性能，依赖安装提速50~100倍
  • uv run自动加载虚拟环境，全程无需手动activate
  • 原生–dev参数隔离开发依赖，打包自动剔除工具包
  • 自动读写pyproject.toml，全局锁定所有依赖版本
  • Windows/Mac/Linux命令完全统一，跨系统无差异
  • 和Ruff同生态，一套工具同时管理依赖+代码规范

三、跨平台一键安装uv

Windows（管理员PowerShell）

irm https://astral.sh/uv/install.ps1 | iex
复制整行粘贴执行，完成后重启终端生效

Mac / Linux 终端

curl -LsSf https://astral.sh/uv/install.sh | sh
执行完毕关闭终端重新打开才能识别uv命令
安装验证：新开终端输入 uv --version，输出版本号代表安装成功。

四、锁定项目Python版本 uv python pin

零基础作用讲解

不同电脑预装Python3.9/3.10/3.12版本混杂，语法、第三方库兼容存在差异。uv python pin 3.12会自动生成.python-version文件，强制本项目统一Python版本，团队所有人打开项目自动匹配，消除版本不兼容报错。

uv python pin 3.12

五、创建隔离虚拟环境 uv venv

零基础讲解虚拟环境

电脑全局Python会安装大量工具包，项目之间包版本要求冲突。虚拟环境.venv是当前项目独立软件仓库，本项目所有依赖仅存放在这里，不会污染全局Python，切换项目无包冲突。

uv venv
Git规范：.venv文件夹体积较大，必须写入.gitignore屏蔽，禁止上传代码仓库。

六、安装/卸载项目依赖 uv add / remove

1. 安装程序运行必需依赖

# 基础格式 uv add 包名
uv add openai python-dotenv pydantic
# 指定最低兼容版本
uv add openai>=1.30.0

2. 卸载无用依赖包

uv remove pydantic

3. 升级所有兼容依赖到最新稳定版

uv sync --upgrade

七、区分运行依赖与开发依赖 –dev

零基础区分概念

运行依赖（无–dev）：程序打包、发给普通用户运行必须的核心包，如AI接口SDK、读取.env工具；

开发依赖（–dev）：仅编码、调试、打包阶段使用，发给用户的exe不需要，打包时自动剔除，减小程序体积。代表工具：ruff、pyinstaller、pytest单元测试。

# 开发专用工具安装
uv add --dev ruff pyinstaller pytest

八、无需手动激活：uv run 运行代码/工具

核心便利点说明

传统venv需要手动执行激活脚本，新手极易忘记，导致程序调用全局包出现版本报错。uv run会自动读取当前目录.venv虚拟环境，不用切换激活命令，直接运行Python脚本或Ruff等工具。

运行项目入口程序

uv run python main.py

运行Ruff代码规范修复

uv run ruff check . –fix

执行单元测试

uv run pytest tests/

九、多人协作统一环境 uv sync

作用讲解

团队其他成员、换电脑开发时，仅拉取代码无本地依赖。执行uv sync自动读取pyproject.toml记录的全部依赖，精准安装对应版本，保证所有人运行环境完全一致，彻底解决“我本地能跑你电脑报错”问题。

uv sync

十、高频辅助查询命令大全

查看当前已安装全部依赖

uv list

检索第三方库

uv search tenacity

打印依赖树，查看冲突

uv tree

清理本地缓存安装包

uv cache clean

十一、完整新项目标准操作流程

  1. 电脑空白处新建项目文件夹，Shift+右键打开终端/PowerShell；
  2. 锁定统一Python版本：
    uv python pin 3.12
  3. 创建隔离虚拟环境：
    uv venv
  4. 安装程序核心运行依赖：
    uv add openai python-dotenv
  5. 安装开发工具包：
    uv add –dev ruff pyinstaller
  6. 编写完代码统一规范：
    uv run ruff format . && uv run ruff check . –fix
  7. 本地启动调试：
    uv run python main.py
  8. 其他开发者拿到项目，仅执行：
    uv sync
    即可完整复现环境
流程总结：一套uv命令覆盖项目从初始化、开发、团队协作全环境管理，无复杂多工具切换，零基础大幅降低Python环境踩坑概率。

uv Full Beginner Tutorial: What It Is & Full Command Reference

All-in-one Python environment manager from Astral, paired with Ruff, cross-platform workflow

Table of Contents

  1. 1 Introduction: Creator & Core Purpose
  2. 2 Drawbacks of pip/venv vs uv Advantages
  3. 3 Cross-Platform Install Script
  4. 4 Pin Python Version uv python pin
  5. 5 Create Isolated Virtual Env uv venv
  6. 6 Add / Remove Dependencies
  7. Dev Dependencies Separation –dev
  8. Run Scripts Without Activate uv run
  9. Sync Env For Team uv sync
  10. Common Helper Commands
  11. Full New Project Workflow

1 Introduction

uv is a Rust-based Python tool developed by Astral (maker of Ruff). It unifies Python version control, virtual environments, dependency management, and script execution into a single toolchain with far better performance than native pip & venv.

2 Comparison

Traditional pip/venv: Slow install, complex activation, cannot split dev deps, inconsistent env across machines.

uv: 50-100x faster, auto env load via uv run, native dev flag, pyproject.toml sync for team collaboration.

Install

# Windows
irm https://astral.sh/uv/install.ps1 | iex
# Mac/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Pin Python Version

uv python pin 3.12

Create Venv

uv venv

Manage Packages

uv add openai pydantic
uv remove pydantic
uv sync --upgrade

Dev Tools

uv add --dev ruff pyinstaller pytest

Run Code

uv run python main.py
uv run ruff check . --fix

Team Sync

uv sync

Helper Commands

uv list
uv search xxx
uv tree
uv cache clean

Full Project Steps

  1. uv python pin 3.12
  2. uv venv
  3. uv add core libs
  4. uv add –dev tools
  5. uv run lint & format
  6. uv run main.py
  7. Others run uv sync to replicate env