目录前言1 初识 uv概述与核心优势1.1 什么是 uv1.2 uv 的核心优势2 安装与配置 uv2.1 安装方法2.2 验证安装与常用命令3 管理 Python 版本3.1 安装与管理 Python 版本3.2 在项目中固定 Python 版本4 虚拟环境管理4.1 创建虚拟环境4.2 激活与使用虚拟环境4.3 uv 的环境发现机制5 项目管理与依赖管理5.1 初始化新项目5.2 核心文件说明5.3 添加与管理依赖5.4 环境同步6 运行脚本与工具管理6.1 运行脚本6.2 管理 CLI 工具7 pip 兼容命令与迁移7.1 使用 uv 替代 pip7.2 命令对照表7.3 迁移现有项目8 常用命令速查结语参考资料前言在 Python 开发领域包管理和环境管理一直是开发者日常工作中最频繁且最令人头疼的环节。传统的 pip virtualenv 组合虽然经典但在面对大型项目或需要快速迭代的场景时往往显得力不从心——依赖安装速度慢、版本锁定不够可靠、多工具切换繁琐等问题一直困扰着开发者。Astral 团队推出的uv正是为解决这些问题而生。作为一款用 Rust 编写的极速 Python 包和项目管理器uv 集成了虚拟环境创建、依赖管理、Python 版本管理、项目初始化等多项功能堪称 Python 生态中的全能选手。本文将系统介绍 uv 的核心概念、安装方法、虚拟环境管理以及项目开发实战帮助读者快速掌握这一现代 Python 开发利器。1 初识 uv概述与核心优势1.1 什么是 uvuv 是由 Astral 公司 Ruff linter 的开发团队推出的一款基于 Rust 编写的 Python 包管理工具旨在成为Python 的 Cargo。它通过一套精心设计的命令集将 Python 开发中的包管理、环境隔离、项目构建等繁琐任务变得简单而高效。与其他 Python 包管理工具相比uv 更像是一个全能选手能够替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv、twine 等多种传统工具。uv 的核心设计理念是用单一工具覆盖 Python 项目开发的完整生命周期从 Python 解释器的安装管理到虚拟环境的创建再到依赖的添加删除和版本锁定最后到项目的打包发布全部可以通过 uv 命令完成。1.2 uv 的核心优势uv 在性能、兼容性和功能上都有出色表现其核心优势主要体现在以下几个方面。性能卓越uv 使用 Rust 编写通过激进缓存、并行下载和高效的依赖解析算法实现了令人惊叹的执行速度。在创建虚拟环境方面uv 比传统的python -m venv快约 56 倍在安装依赖时从温缓存安装 23 个包uv 仅需 0.15 秒而 pip 需要 6.6 秒速度提升约 44 倍。这种速度优势在日常开发和 CI/CD 场景中都极具价值。多功能集成uv 不只是一个快速的包安装器更是一个集包管理、虚拟环境、项目管理、CLI 工具安装于一体的综合性工具链。使用 uv开发者无需再组合使用 pyenv 管理 Python 版本、virtualenv 创建虚拟环境、pip-tools 锁定依赖、pipx 安装 CLI 工具等多种工具一套命令走天下。开发体验uv 借鉴了 Node.js 和 Rust 的依赖管理方式提供了类似npm install和cargo add的直观命令。项目结构清晰依赖声明和版本锁定由工具自动管理让开发者能够专注于业务代码而非环境配置。向后兼容使用 uv 创建的项目仍然兼容 pip 和其他 Python 工具。uv 使用标准的pyproject.toml进行配置生成的uv.lock锁文件遵循跨平台规范可以与团队中未使用 uv 的成员无缝协作。2 安装与配置 uv2.1 安装方法uv 的安装非常简单支持多种安装方式。以下是官方推荐的安装方法。Linux 和 macOS 系统可以使用官方提供的安装脚本通过 curl 执行一键安装curl-LsSfhttps://astral.sh/uv/install.sh|shWindows 系统可以在 PowerShell 中执行以下命令完成安装powershell-ExecutionPolicy ByPass-cirm https://astral.sh/uv/install.ps1 | iex除了官方安装脚本外还可以使用 Homebrew 包管理器进行安装适用于 macOS 和 Linuxbrewinstalluv如果系统中已经安装了 Python也可以直接使用 pip 安装 uvpipinstalluv2.2 验证安装与常用命令安装完成后可以通过以下命令验证 uv 是否安装成功以及查看版本信息uv--version更新 uv 到最新版本可以使用uv self update命令uv self update当需要查看帮助信息时可以使用uv help命令。如果不指定具体命令它会列出所有可用的顶级命令如果指定了子命令则会显示该命令的详细参数说明uvhelpuvhelpadd3 管理 Python 版本3.1 安装与管理 Python 版本uv 的一大亮点是内置了 Python 版本管理功能无需单独安装 pyenv 即可管理多个 Python 版本。使用uv python install命令可以安装指定版本的 Pythonuv pythoninstall3.12uv pythoninstall3.13如果要同时安装多个版本可以在命令中列出所有需要的版本号uv pythoninstall3.113.123.13查看已安装的 Python 版本列表可以使用uv python list命令uv python list该命令会显示所有已安装的 Python 版本及其路径信息。值得注意的是uv 使用预编译的二进制文件分发 Python相比从源码编译的 pyenv安装速度大大提升通常只需几秒钟即可完成。3.2 在项目中固定 Python 版本在项目中使用uv python pin命令可以将项目固定到特定 Python 版本uv python pin3.12该命令会在项目中创建.python-version文件后续执行uv sync或uv run时uv 会自动使用该版本或在需要时自动下载安装。4 虚拟环境管理4.1 创建虚拟环境虚拟环境是 Python 项目隔离的基石。uv 的虚拟环境管理命令既强大又直观无需再混合使用python -m venv和source activate等命令。创建虚拟环境的基本命令是uv venv默认情况下会在当前目录下创建.venv目录uv venv如果需要指定虚拟环境的路径或名称可以使用--path或--name参数uv venv--namemy-env--path~/envs/my-env创建时指定 Python 版本只需使用--python参数uv venv--python3.11提示如果指定的 Python 版本尚未安装uv 会自动下载并安装该版本。4.2 激活与使用虚拟环境创建虚拟环境后在 POSIX 系统Linux/macOS上激活环境的命令如下source.venv/bin/activate在 Windows PowerShell 中激活命令为.venv\Scripts\activate其他 Shell 的激活脚本路径可参考下表。Shell激活脚本fish.venv/bin/activate.fishcsh/tcsh.venv/bin/activate.cshNushell.venv\Scripts\activate.nu使用deactivate命令可以退出当前虚拟环境deactivate4.3 uv 的环境发现机制uv 在执行包管理命令时会按照一定顺序自动发现虚拟环境。首先查找通过VIRTUAL_ENV环境变量激活的虚拟环境然后查找 Conda 环境通过CONDA_PREFIX最后在当前目录或最近的父目录中查找.venv目录。如果未找到任何环境uv 会提示创建新环境或使用--system参数安装到系统 Python。使用VIRTUAL_ENV环境变量指定环境的方式VIRTUAL_ENV/path/to/venv uv pipinstallruff5 项目管理与依赖管理5.1 初始化新项目使用uv init命令可以快速初始化一个新的 Python 项目uv init my-project初始化后uv 会自动生成项目的基本文件结构包括.gitignore、.python-version、pyproject.toml、README.md以及一个示例 Python 文件。需要注意的是uv init默认会初始化 Git 仓库。初始化库项目而非应用程序项目可以使用--lib参数uv init--libmy-package5.2 核心文件说明uv 项目中有两个核心文件需要特别关注pyproject.toml和uv.lock。pyproject.toml是项目配置文件用于声明项目的元数据、依赖和构建配置。该文件遵循 PEP 621 规范是 Python 生态的事实标准。uv.lock是自动生成的锁文件记录了所有直接依赖和间接依赖的确切版本号。这个文件不应手动编辑只由 uv 工具自动维护。建议将uv.lock纳入版本控制以确保所有开发者和部署环境使用完全一致的依赖版本。5.3 添加与管理依赖添加依赖是日常开发中最频繁的操作之一。使用uv add命令可以方便地添加包依赖uvaddrequests添加指定版本的依赖uvaddrequests2.31.0添加开发依赖可以使用--dev参数uvadd--devpytest使用--group参数可以区分不同环境的依赖uvadd--groupdev pytest uvadd--groupproduction gunicorn删除依赖使用uv remove命令该命令会自动清理相关的传递依赖uv remove requests5.4 环境同步创建或修改依赖后需要执行uv sync命令同步环境。该命令会自动完成以下操作检查 Python 版本 → 创建或更新虚拟环境 → 生成或更新uv.lock→ 安装所有依赖。uvsync如果只想按照锁文件安装不更新锁文件可以使用--locked参数uvsync--locked在 CI/CD 环境中使用--frozen参数可以确保严格按锁文件安装uvsync--frozen6 运行脚本与工具管理6.1 运行脚本使用uv run命令可以直接在项目环境中运行脚本无需先激活虚拟环境uv run python main.py首次运行uv run时如果环境中尚未创建虚拟环境uv 会自动完成 Python 版本选择、虚拟环境创建、uv.lock生成以及依赖安装等一系列准备工作。uv 还支持 PEP 723 规范的内联依赖脚本。在脚本开头以特殊注释形式声明依赖运行时 uv 会自动管理# /// script# dependencies [requests, rich]# requires-python 3.11# ///importrequestsfromrichimportprintresponserequests.get(https://api.github.com/zen)print(response.text)6.2 管理 CLI 工具uv 提供了两种使用 CLI 工具的方式。对于偶尔使用的工具可以使用uvx命令相当于uv tool run在临时隔离环境中运行无需永久安装uvx ruff check.uvx black--check.如果需要长期使用某个工具可以使用uv tool install命令将其安装到全局工具目录uv toolinstallruff升级已安装的工具可以使用uv tool upgrade命令uv tool upgrade ruff uv tool upgrade--all7 pip 兼容命令与迁移7.1 使用 uv 替代 pip对于习惯使用 pip 的开发者uv 提供了完全兼容的命令接口只需在原有命令前加上uv pip前缀即可。例如uv pipinstallflask requests uv pipinstall-rrequirements.txt uv pip uninstall flask使用uv pip compile命令可以编译依赖相当于 pip-tools 的 pip-compile生成锁定的 requirements 文件uv pip compile requirements.in-orequirements.txt使用uv pip sync命令可以按照 requirements 文件同步环境uv pipsyncrequirements.txt7.2 命令对照表为方便从传统工具迁移到 uv以下列出主要命令的对照关系。pip/virtualenv 命令uv 等价命令说明python -m venv .venvuv venv创建虚拟环境pip install packageuv add package安装包并更新项目文件pip install -r requirements.txtuv pip install -r requirements.txt从 requirements 文件安装pip freeze requirements.txtuv export -o requirements.txt导出依赖到文件pip listuv pip list列出已安装的包pip uninstall packageuv remove package卸载包pyenv install 3.12uv python install 3.12安装 Python 版本pipx install tooluv tool install tool安装 CLI 工具poetry inituv init初始化项目poetry add packageuv add package添加依赖poetry syncuv sync同步环境7.3 迁移现有项目将现有项目迁移到使用 uv 管理非常简单只需以下几步即可完成。首先在项目目录下初始化 uv 项目如果项目已有pyproject.toml可以跳过uv init然后同步环境安装所有依赖uvsync之后就可以使用 uv 的所有命令来管理项目了。原项目的requirements.txt文件仍然可以使用uv pip install -r requirements.txt来安装迁移过程非常平滑。8 常用命令速查为方便日常使用将本文中涉及的主要命令整理如下。命令作用uv --version查看 uv 版本uv self update更新 uv 到最新版本uv help查看帮助信息uv python install 3.12安装指定版本的 Pythonuv python list列出已安装的 Python 版本uv python pin 3.12固定项目使用 Python 3.12uv venv创建虚拟环境uv venv --python 3.11创建基于 Python 3.11 的虚拟环境uv init my-project初始化新项目uv add package添加依赖uv add --dev pytest添加开发依赖uv add --group prod package添加生产环境依赖uv remove package移除依赖uv sync同步环境uv run python script.py运行脚本uv pip install package使用 pip 兼容方式安装包uv pip compile requirements.in -o requirements.txt编译依赖文件uv tool install ruff安装 CLI 工具uvx ruff check .临时运行 CLI 工具uv format格式化代码uv check检查项目依赖结语uv 通过一套精心设计的命令集将 Python 开发的包管理、环境隔离、项目构建等繁琐任务变得简单而高效。其核心优势在于极致的速度和一体化的体验。从uv add管理依赖到uv venv管理环境从uv run无缝执行脚本到uv tool install安装 CLI 工具uv 覆盖了现代 Python 开发的全链路。无论你是处理大型 Python 项目的资深工程师还是刚刚开始学习 Python 的新手将 uv 纳入工具链都将显著提升开发效率和体验。uv 的设计哲学体现了现代开发工具的趋势用更少的工具、做更多的事、达到更高的效率。现在就开始探索 uv打造你更流畅的 Python 工作流吧。参考资料1 uv 官方文档https://docs.astral.sh/uv/2 Astral 官网https://astral.sh/3 AppSignal Blog - Switching from Pip to uv in Python: A Comprehensive Guidehttps://blog.appsignal.com/2025/09/24/switching-from-pip-to-uv-in-python-a-comprehensive-guide.html4 博客园 - 从入门到精通UV 现代 Python 包管理器全命令详解与实战指南https://www.cnblogs.com/ljbguanli/p/197525605 博客园 - Python包管理不再头疼uv工具快速上手https://www.cnblogs.com/wang_yb/p/186354416 pydevtools - uv: A Complete Guide to Python’s Fastest Package Managerhttps://pydevtools.com/handbook/explanation/uv-complete-guide