python uv 基本使用教程

前言先澄清一个身份问题uv不是 Python 标准库的一部分。它由 Astral 公司开发用 Rust 写成官方对自己的介绍是「一个极快的 Python 包管理器和项目管理器」。要使用它需要单独安装它本身标准库里没有uv这个模块import uv也不会成功。本文讲的是命令行工具uv不是某个可以import的库。uv想解决的是 Python 生态里长期存在的碎片化问题装环境要venv装包要pip锁依赖要pip-tools或poetry跑脚本还要管解释器版本。uv把这些能力收进一个可执行文件里同时借助 Rust 实现获得较快的启动与解析速度。它既能像pip那样操作虚拟环境里的包uv pip子命令也能像poetry那样把一个项目从依赖声明到锁定、运行整套管起来。本文介绍uv的定位、安装思路、几组最常见的命令以及它与pip、venv、pyproject.toml的关系。所有命令的具体参数与最新行为请以 uv 官方文档为准本文只讲稳定的主干用法。一、uv 的定位包管理器 项目管理器官方文档给的定位是「package and project manager」。这两个词对应两套用法用法面向对象典型命令类比包管理已有的虚拟环境uv pip install、uv pip freeze替代pip项目管理一个项目目录uv init、uv add、uv sync、uv run类似poetry环境管理解释器与虚拟环境uv venv、uv python install替代venv工具运行一次性的命令行工具uv tool相关命令类似pipx「极快」是营销描述官方页面把它写在简介里。不写具体倍数是本文的原则——速度受网络、缓存、平台影响很大想知道差异请自己测。# 查看版本与帮助uv 需要先安装不属于标准库uv --versionuv --help上面这段是bash不是 Pythonuv是一个可执行程序在终端里运行不能写进.py文件里执行。二、安装与版本uv有自己的安装方式官方提供了独立的安装脚本和包管理器渠道。具体命令随平台和发布时间变化请以官方文档的安装章节为准。这里只强调一个安全习惯不要随手粘贴来源不明的安装脚本到终端。# 示意uv 的安装方式请以官方文档为准# 常见渠道包括独立安装脚本、包管理器如 Homebrew、Scoop、Winget等# 无论用哪种都应从官方文档给出的地址获取装好之后可以用uv --version确认可用。uv只管 Python 的包与项目它自己需要能连上包索引默认是 PyPI这一步和pip一样受网络环境影响。三、虚拟环境uv venv虚拟环境virtual environment的作用是把某个项目的依赖和系统环境隔离开。uv venv用来创建一个虚拟环境用法与标准库的venv思路一致。# 在项目目录里创建虚拟环境具体参数以官方文档为准uv venv# 指定 Python 版本uv venv --python 3.12创建之后目录里会出现一个虚拟环境文件夹传统上叫.venv。激活方式与venv相同Linux / macOS 上source .venv/bin/activateWindows 上运行.venv\Scripts\activate。不过用uv时很多时候根本不需要手动激活。uv run会自动查找并使用当前项目的虚拟环境这也是它比传统流程省事的地方之一。四、包安装uv pipuv pip这一族子命令的接口刻意向pip靠拢让熟悉pip的人能直接上手。# 安装包会自动使用当前项目/已激活的虚拟环境uv pip install requests# 从 requirements.txt 安装uv pip install -r requirements.txt# 导出当前环境的依赖清单uv pip freeze requirements.txt# 查看已安装的包uv pip list这里有一个必须反复强调的点这些命令要么作用于已激活的虚拟环境要么需要显式指定目标环境。uv pip一族命令设计上默认不会往系统环境里装东西这与直接在系统 Python 上执行pip install的行为形成鲜明对比也是迁移时最容易踩空的地方。如果确实要对某个环境操作官方文档给出了显式指定环境路径的参数本节不逐字复述以免版本差异导致记错。五、项目模式pyproject.toml 与 uv run当uv以「项目管理器」的身份工作时项目的依赖声明写在pyproject.toml里。这个文件是 Python 打包生态的通用配置文件PEP 518 引入[build-system]PEP 621 规范了[project]元数据不是uv专有的。# pyproject.toml 示例字段语义以 Python 打包官方文档与 uv 文档为准[project]name demo-appversion 0.1.0requires-python 3.9dependencies [requests2.31,]配套的常见命令# 初始化一个新项目生成 pyproject.tomluv init# 添加依赖会更新 pyproject.toml 与锁定文件uv add requests# 按锁定文件同步环境uv sync# 运行脚本或命令自动使用项目的虚拟环境uv run example.py# 运行某个已安装的命令行工具uv run ruff checkuv run的便利在于它负责找到必要时创建正确的环境再在其中执行你的命令你不必先激活环境。新增依赖会写入锁文件其他机器上uv sync就能还原出一致的环境——这正是「可复现环境」要解决的问题。六、和 pip、venv 的关系关注点pip venv标准库/官方工具uv是否随 Python 附带pip 通常随 Python 附带venv 是标准库模块需要单独安装依赖声明requirements.txtpyproject.toml项目模式锁定需借助其它工具有锁文件机制运行脚本先激活环境再python x.pyuv run x.py一条命令兼容 pip 接口—uv pip子命令尽量对齐需要说明的是uv并不「取代」标准库的venv概念——它仍然在创建和使用虚拟环境只是把步骤包装得更顺手。如果你只想要一个最小可用的方案python -m venv加python -m pip依然是完全够用的官方路径。七、一个最小工作流把上面的命令串起来从零到一个能跑的项目大致是这样# 1. 建项目目录并进入mkdir my-project cd my-project# 2. 初始化项目生成 pyproject.tomluv init# 3. 创建虚拟环境uv run 也可按需自动创建uv venv# 4. 添加一个依赖uv add requests# 5. 写一个脚本后直接运行uv run hello.py对应的hello.py可以简单到只有几行# 适用于 Python 3.9import sysdef main():print(Python 版本, sys.version.split()[0])try:import requestsprint(requests 可用版本, requests.__version__)except ImportError:print(当前环境没有安装 requests)if __name__ __main__:main()逐行推演sys.version是一个字符串split()[0]取第一段即版本号。import requests放在try里是因为没装依赖时应当给出提示而不是直接崩溃——这在多人协作、环境不齐时很实用。注意这里没有编造requests的任何具体 API只用它一个确实存在的__version__属性做演示。常见坑点坑点 1以为 uv 是标准库模块。❌import uv或在requirements.txt里写uv后import uv——它不是可导入的库是命令行工具。 ✅ 把它当外部程序安装并在终端调用Python 代码里不要import uv。坑点 2把 uv 的命令写进 .py 文件。❌ 在 Python 文件里写uv pip install requests当语句——这是 shell 语法Python 会报SyntaxError。 ✅ 区分场合.py文件里用subprocess调外部程序或者干脆在终端里手动执行这些命令。坑点 3依赖装进了错误的环境。❌ 直接pip install装到系统 Python然后又用uv run跑项目——两者用的是不同环境ImportError找不到包。 ✅ 项目内统一走uv add/uv sync让依赖落在项目的虚拟环境里。坑点 4忘记提交锁文件。❌ 只提交pyproject.toml不提交锁定文件——别的机器uv sync时解析到的版本可能和你的不一致。 ✅ 把锁文件一并纳入版本控制保证环境可复现。坑点 5以为 uv 能自动解决所有版本冲突。❌ 同时声明互相矛盾的版本范围指望工具「想办法」——依赖解析失败会直接报错退出。 ✅ 放宽或收紧版本约束让约束集合有解冲突信息通常已经指出是哪两个包打架。坑点 6照搬旧教程里的 uv 参数。❌ 从旧博客抄一条uv命令参数在当前版本已改名——命令报 unknown option。 ✅ 以 uv 官方文档为准本文展示的都是主干用法具体参数请对照官方文档核对。坑点 7在没有项目文件时用项目模式命令。❌ 在一个空目录里直接uv sync/uv add——没有pyproject.toml命令会失败或提示先初始化。 ✅ 先uv init生成项目骨架再做后续操作。坑点 8以为装了 uv 就不用管虚拟环境了。❌ 认为 uv 会让依赖「全局可用」——它仍然基于虚拟环境隔离依赖。 ✅ 需要跨项目共享的命令行工具用工具安装相关子命令项目依赖则留在项目环境内。总结场景命令说明创建虚拟环境uv venv参数以官方文档为准装包uv pip install 包名对齐 pip 接口导出依赖uv pip freeze用途同 pip初始化项目uv init生成pyproject.toml添加依赖uv add 包名更新声明与锁定同步环境uv sync按锁定文件还原运行脚本/工具uv run 命令自动使用项目环境uv的价值在于把「建环境、装依赖、锁版本、跑脚本」四件事收进一套命令并且提供了与pip接近的接口方便迁移。但它终究是一个第三方工具不是标准库的一部分用它之前先装好它本身用它的命令时以官方文档为准就不会出岔子。