一、参考资料安装 | uv 中文文档项目开发 | uv 中文文档uv 入门教程 — Python 包与环境管理工具 | 菜鸟教程二、uv常用操作1. 安装uv# curl 方式$curl-LsSfhttps://astral.sh/uv/install.sh|sh# wget 方式$wget-qO- https://astral.sh/uv/install.sh|sh# 安装指定版本$curl-LsSfhttps://astral.sh/uv/0.7.4/install.sh|sh# 升级 uv$ uv self update输出示例$ yoyoyoyo:/media/sda3/cache$wget-qO- https://astral.sh/uv/install.sh|shdownloading uv0.11.7 x86_64-unknown-linux-gnu installing to /home/yoyo/.local/bin uv uvx everythings installed!$ yoyoyoyo:/media/sda3/cache$ uv--versionuv0.11.7(x86_64-unknown-linux-gnu)Shell 自动补全# 为 uv 命令启用 shell 自动补全$echoeval $(uv generate-shell-completion bash)~/.bashrc2. 卸载uv清理存储的数据$ uv cache clean $rm-r$(uv pythondir)$rm-r$(uv tooldir)删除 uv 二进制文件$rm~/.local/bin/uv3. 管理Python版本查看Python版本$ uv python list输出示例$ yoyoyoyo:/media/sda3/cache/hello-world$ uv python list cpython-3.15.0a8-linux-x86_64-gnudownload availablecpython-3.15.0a8freethreaded-linux-x86_64-gnudownload availablecpython-3.14.4-linux-x86_64-gnudownload availablecpython-3.14.4freethreaded-linux-x86_64-gnudownload availablecpython-3.13.13-linux-x86_64-gnudownload availablecpython-3.13.13freethreaded-linux-x86_64-gnudownload availablecpython-3.12.13-linux-x86_64-gnudownload availablecpython-3.11.15-linux-x86_64-gnudownload availablecpython-3.10.20-linux-x86_64-gnudownload availablecpython-3.9.25-linux-x86_64-gnudownload availablecpython-3.8.20-linux-x86_64-gnudownload availablecpython-3.8.10-linux-x86_64-gnu /usr/bin/python3.8 cpython-3.8.10-linux-x86_64-gnu /usr/bin/python3 -/usr/bin/python3.8 cpython-3.7.17-linux-x86_64-gnu /usr/bin/python3.7 pypy-3.11.15-linux-x86_64-gnudownload availablepypy-3.10.16-linux-x86_64-gnudownload availablepypy-3.9.19-linux-x86_64-gnudownload availablepypy-3.8.16-linux-x86_64-gnudownload availablegraalpy-3.12.0-linux-x86_64-gnudownload availablegraalpy-3.11.0-linux-x86_64-gnudownload availablegraalpy-3.10.0-linux-x86_64-gnudownload availablegraalpy-3.8.5-linux-x86_64-gnudownload available安装指定版本$ uv pythoninstall3.12初始化项目时指定 Python 版本$ uv init--python3.12# 通过路径指定$ uv init--python/path/to/python切换 Python 版本# Pin new version$ uv python pin3.10# Or recreate venv with specific version$ uv venv--python3.10# Resync dependencies$ uvsync输出示例$ yoyoyoyo:/media/sda3/cache/hello-world$source.venv/bin/activate $(hello-world)czubuntu:/media/sda3/cache/hello-world$ python--versionPython3.12.13 $(hello-world)czubuntu:/media/sda3/cache/hello-world$ uv python pin3.8Updated.python-versionfrom3.12-3.8$(hello-world)czubuntu:/media/sda3/cache/hello-world$ uvsyncUsing CPython3.8.10 interpreter at: /usr/bin/python3.8 Removed virtual environment at: .venv Creating virtual environment at: .venv Resolved1packagein0.81ms Checkedin0.01ms $(hello-world)czubuntu:/media/sda3/cache/hello-world$ python--versionPython3.8.104. 管理虚拟环境创建虚拟环境# 在当前目录创建名为 .venv 的虚拟环境使用系统默认 Python$ uv venv# 指定 Python 版本$ uv venv--python3.12激活虚拟环境$source.venv/bin/activate退出虚拟环境$ deactivate输出示例$ yoyoyoyo:/media/sda3/cache/hello-world$ uv venv--python3.12Using CPython3.12.13 Creating virtual environment at: .venv Activate with:source.venv/bin/activate $ yoyoyoyo:/media/sda3/cache/hello-world$source.venv/bin/activate(hello-world)yoyoyoyo:/media/sda3/cache/hello-world$ python--versionPython3.12.135. 包管理uv 提供了与 pip 完全兼容的命令接口可以直接替换已有工作流中的 pip 命令。查看包列表$ uv pip list安装包# 安装最新版本$ uv pipinstallrequests# 安装指定版本$ uv pipinstallrequests2.31.0# 从 requirements.txt 批量安装$ uv pipinstall-rrequirements.txt升级包$ uv pipinstall--upgraderequests卸载包$ uv pip uninstall requests查看已安装的包$ uv pip list导出当前环境的依赖到requirements.txt文件$ uv pip freezerequirements.txt三、项目管理推荐方式uv 支持以pyproject.toml为中心的现代项目管理方式这是比 pip 模式更推荐的使用方法尤其适合团队协作和多环境部署。1. 初始化项目$ uv init hello-world $cdhello-world或者在工作目录中初始化一个项目$mkdirhello-world $cdhello-world $ uv init输出示例$ yoyoyoyo:/media/sda3/cache$ uv init hello-world Initialized projecthello-worldat/media/sda3/cache/hello-worlduv将创建以下文件$ yoyoyoyo:/media/sda3/cache/hello-world$ tree-L1-a./ ./ ├── .git ├── .gitignore ├── main.py ├── pyproject.toml# 项目配置和依赖声明├── .python-version# 固定 Python 版本└── README.mdmain.py文件包含一个简单的Hello world程序。使用uv run指令运行$ yoyoyoyo:/media/sda3/cache/hello-world$ uv run main.py Using CPython3.8.10 interpreter at: /usr/bin/python3.8 Creating virtual environment at: .venv Hello from hello-world!2. 项目结构除了uv init创建的文件外在首次运行项目uv还会在项目根目录创建.venv虚拟环境 和uv.lock文件。完整的目录结构如下$ yoyoyoyo:/media/sda3/cache/hello-world$ tree-L2-a./ ./ ├── .git │ ├── branches │ ├── config │ ├── description │ ├── HEAD │ ├── hooks │ ├── info │ ├── objects │ └── refs ├── .gitignore ├── main.py ├── pyproject.toml ├── .python-version ├── README.md ├── uv.lock └── .venv ├── bin ├── CACHEDIR.TAG ├── .gitignore ├── lib ├── lib64 -lib ├── .lock └── pyvenv.cfgpyproject.tomlpyproject.toml文件包含项目的元数据[project] name hello-world version 0.1.0 description Add your description here readme README.md requires-python 3.8 dependencies [].python-version.python-version文件包含项目的默认Python版本。.venv.venv目录包含项目的虚拟环境uv将在该目录安装项目依赖项。uv.lockuv.lock是一个跨平台的锁定文件其中包含有关项目依赖项的确切信息。uv.lock是一个人类可读的 TOML 文件但由 uv 管理不应手动编辑。3. 管理依赖项# 添加最新版本$ uvaddrequests# 添加指定版本$ uvaddrequests2.31.0# 从 requirements.txt 添加所有依赖$ uvadd-rrequirements.txt-cconstraints.txt# 移除$ uv remove requests# 升级$ uv lock --upgrade-package requests克隆项目或更新pyproject.toml后运行uv sync指令一键安装所有依赖$ uvsyncuv sync类似于pip install -r requirements.txt它会根据pyproject.toml和uv.lock安装所有依赖确保环境与其他开发者完全一致。如果安装速度慢可以在pyproject.toml中设置国内镜像源[tool.uv]index-urlhttps://pypi.tuna.tsinghua.edu.cn/simple4. 生成/更新锁文件$ uv lock该命令会解析pyproject.toml中的依赖并生成或更新uv.lock文件。uv.lock应该提交到版本库确保团队所有成员使用完全相同的依赖版本。5. 运行脚本uv run是 uv 中非常实用的命令可以无需手动激活虚拟环境直接运行脚本或命令uv 会自动找到并使用正确的环境# 直接运行 Python 脚本$ uv run main.py# 运行项目中的测试$ uv run pytest# 运行任意命令在虚拟环境的上下文中执行$ uv run python-cimport requests; print(requests.__version__)使用uv run相比手动激活环境的优势不会误用错误的 Python 版本也不会忘记激活环境导致包找不到特别适合在 CI/CD 和脚本自动化中使用。例如运行 flask$ uvaddflask $ uv run -- flask run-p3000或者运行一个脚本example.pyimportflaskprint(hello world)$ uv run example.py6. 构建发行版本$ uv build $lsdist/ hello_world-0.1.0-py3-none-any.whl hello_world-0.1.0.tar.gz输出示例$ yoyoyoyo:/media/sda3/cache/hello-world$ uv build Buildingsourcedistribution... running egg_info creating hello_world.egg-info writing hello_world.egg-info/PKG-INFO writing dependency_links to hello_world.egg-info/dependency_links.txt writing top-level names to hello_world.egg-info/top_level.txt writing manifestfilehello_world.egg-info/SOURCES.txtreading manifestfilehello_world.egg-info/SOURCES.txtwriting manifestfilehello_world.egg-info/SOURCES.txtrunning sdist running egg_info writing hello_world.egg-info/PKG-INFO writing dependency_links to hello_world.egg-info/dependency_links.txt writing top-level names to hello_world.egg-info/top_level.txt reading manifestfilehello_world.egg-info/SOURCES.txtwriting manifestfilehello_world.egg-info/SOURCES.txtrunning check creating hello_world-0.1.0 creating hello_world-0.1.0/hello_world.egg-info copying files to hello_world-0.1.0... copying README.md -hello_world-0.1.0 copying main.py -hello_world-0.1.0 copying pyproject.toml -hello_world-0.1.0 copying hello_world.egg-info/PKG-INFO -hello_world-0.1.0/hello_world.egg-info copying hello_world.egg-info/SOURCES.txt -hello_world-0.1.0/hello_world.egg-info copying hello_world.egg-info/dependency_links.txt -hello_world-0.1.0/hello_world.egg-info copying hello_world.egg-info/top_level.txt -hello_world-0.1.0/hello_world.egg-info copying hello_world.egg-info/SOURCES.txt -hello_world-0.1.0/hello_world.egg-info Writing hello_world-0.1.0/setup.cfg Creatingtararchive removinghello_world-0.1.0(and everything under it)Building wheel fromsourcedistribution... running egg_info writing hello_world.egg-info/PKG-INFO writing dependency_links to hello_world.egg-info/dependency_links.txt writing top-level names to hello_world.egg-info/top_level.txt reading manifestfilehello_world.egg-info/SOURCES.txtwriting manifestfilehello_world.egg-info/SOURCES.txtrunning bdist_wheel running build running build_py creating build/lib copying main.py -build/lib running egg_info writing hello_world.egg-info/PKG-INFO writing dependency_links to hello_world.egg-info/dependency_links.txt writing top-level names to hello_world.egg-info/top_level.txt reading manifestfilehello_world.egg-info/SOURCES.txtwriting manifestfilehello_world.egg-info/SOURCES.txtinstalling to build/bdist.linux-x86_64/wheel runninginstallrunning install_lib creating build/bdist.linux-x86_64/wheel copying build/lib/main.py -build/bdist.linux-x86_64/wheel/. running install_egg_info Copying hello_world.egg-info to build/bdist.linux-x86_64/wheel/./hello_world-0.1.0-py3.8.egg-info running install_scripts creating build/bdist.linux-x86_64/wheel/hello_world-0.1.0.dist-info/WHEEL creating/media/sda3/cache/hello-world/dist/.tmp-k3_8cna4/hello_world-0.1.0-py3-none-any.whland addingbuild/bdist.linux-x86_64/wheelto it addingmain.pyaddinghello_world-0.1.0.dist-info/METADATAaddinghello_world-0.1.0.dist-info/WHEELaddinghello_world-0.1.0.dist-info/top_level.txtaddinghello_world-0.1.0.dist-info/RECORDremoving build/bdist.linux-x86_64/wheel Successfully built dist/hello_world-0.1.0.tar.gz Successfully built dist/hello_world-0.1.0-py3-none-any.whl Ubuntu系统下快速体验uv虚拟环境管理
一、参考资料安装 | uv 中文文档项目开发 | uv 中文文档uv 入门教程 — Python 包与环境管理工具 | 菜鸟教程二、uv常用操作1. 安装uv# curl 方式$curl-LsSfhttps://astral.sh/uv/install.sh|sh# wget 方式$wget-qO- https://astral.sh/uv/install.sh|sh# 安装指定版本$curl-LsSfhttps://astral.sh/uv/0.7.4/install.sh|sh# 升级 uv$ uv self update输出示例$ yoyoyoyo:/media/sda3/cache$wget-qO- https://astral.sh/uv/install.sh|shdownloading uv0.11.7 x86_64-unknown-linux-gnu installing to /home/yoyo/.local/bin uv uvx everythings installed!$ yoyoyoyo:/media/sda3/cache$ uv--versionuv0.11.7(x86_64-unknown-linux-gnu)Shell 自动补全# 为 uv 命令启用 shell 自动补全$echoeval $(uv generate-shell-completion bash)~/.bashrc2. 卸载uv清理存储的数据$ uv cache clean $rm-r$(uv pythondir)$rm-r$(uv tooldir)删除 uv 二进制文件$rm~/.local/bin/uv3. 管理Python版本查看Python版本$ uv python list输出示例$ yoyoyoyo:/media/sda3/cache/hello-world$ uv python list cpython-3.15.0a8-linux-x86_64-gnudownload availablecpython-3.15.0a8freethreaded-linux-x86_64-gnudownload availablecpython-3.14.4-linux-x86_64-gnudownload availablecpython-3.14.4freethreaded-linux-x86_64-gnudownload availablecpython-3.13.13-linux-x86_64-gnudownload availablecpython-3.13.13freethreaded-linux-x86_64-gnudownload availablecpython-3.12.13-linux-x86_64-gnudownload availablecpython-3.11.15-linux-x86_64-gnudownload availablecpython-3.10.20-linux-x86_64-gnudownload availablecpython-3.9.25-linux-x86_64-gnudownload availablecpython-3.8.20-linux-x86_64-gnudownload availablecpython-3.8.10-linux-x86_64-gnu /usr/bin/python3.8 cpython-3.8.10-linux-x86_64-gnu /usr/bin/python3 -/usr/bin/python3.8 cpython-3.7.17-linux-x86_64-gnu /usr/bin/python3.7 pypy-3.11.15-linux-x86_64-gnudownload availablepypy-3.10.16-linux-x86_64-gnudownload availablepypy-3.9.19-linux-x86_64-gnudownload availablepypy-3.8.16-linux-x86_64-gnudownload availablegraalpy-3.12.0-linux-x86_64-gnudownload availablegraalpy-3.11.0-linux-x86_64-gnudownload availablegraalpy-3.10.0-linux-x86_64-gnudownload availablegraalpy-3.8.5-linux-x86_64-gnudownload available安装指定版本$ uv pythoninstall3.12初始化项目时指定 Python 版本$ uv init--python3.12# 通过路径指定$ uv init--python/path/to/python切换 Python 版本# Pin new version$ uv python pin3.10# Or recreate venv with specific version$ uv venv--python3.10# Resync dependencies$ uvsync输出示例$ yoyoyoyo:/media/sda3/cache/hello-world$source.venv/bin/activate $(hello-world)czubuntu:/media/sda3/cache/hello-world$ python--versionPython3.12.13 $(hello-world)czubuntu:/media/sda3/cache/hello-world$ uv python pin3.8Updated.python-versionfrom3.12-3.8$(hello-world)czubuntu:/media/sda3/cache/hello-world$ uvsyncUsing CPython3.8.10 interpreter at: /usr/bin/python3.8 Removed virtual environment at: .venv Creating virtual environment at: .venv Resolved1packagein0.81ms Checkedin0.01ms $(hello-world)czubuntu:/media/sda3/cache/hello-world$ python--versionPython3.8.104. 管理虚拟环境创建虚拟环境# 在当前目录创建名为 .venv 的虚拟环境使用系统默认 Python$ uv venv# 指定 Python 版本$ uv venv--python3.12激活虚拟环境$source.venv/bin/activate退出虚拟环境$ deactivate输出示例$ yoyoyoyo:/media/sda3/cache/hello-world$ uv venv--python3.12Using CPython3.12.13 Creating virtual environment at: .venv Activate with:source.venv/bin/activate $ yoyoyoyo:/media/sda3/cache/hello-world$source.venv/bin/activate(hello-world)yoyoyoyo:/media/sda3/cache/hello-world$ python--versionPython3.12.135. 包管理uv 提供了与 pip 完全兼容的命令接口可以直接替换已有工作流中的 pip 命令。查看包列表$ uv pip list安装包# 安装最新版本$ uv pipinstallrequests# 安装指定版本$ uv pipinstallrequests2.31.0# 从 requirements.txt 批量安装$ uv pipinstall-rrequirements.txt升级包$ uv pipinstall--upgraderequests卸载包$ uv pip uninstall requests查看已安装的包$ uv pip list导出当前环境的依赖到requirements.txt文件$ uv pip freezerequirements.txt三、项目管理推荐方式uv 支持以pyproject.toml为中心的现代项目管理方式这是比 pip 模式更推荐的使用方法尤其适合团队协作和多环境部署。1. 初始化项目$ uv init hello-world $cdhello-world或者在工作目录中初始化一个项目$mkdirhello-world $cdhello-world $ uv init输出示例$ yoyoyoyo:/media/sda3/cache$ uv init hello-world Initialized projecthello-worldat/media/sda3/cache/hello-worlduv将创建以下文件$ yoyoyoyo:/media/sda3/cache/hello-world$ tree-L1-a./ ./ ├── .git ├── .gitignore ├── main.py ├── pyproject.toml# 项目配置和依赖声明├── .python-version# 固定 Python 版本└── README.mdmain.py文件包含一个简单的Hello world程序。使用uv run指令运行$ yoyoyoyo:/media/sda3/cache/hello-world$ uv run main.py Using CPython3.8.10 interpreter at: /usr/bin/python3.8 Creating virtual environment at: .venv Hello from hello-world!2. 项目结构除了uv init创建的文件外在首次运行项目uv还会在项目根目录创建.venv虚拟环境 和uv.lock文件。完整的目录结构如下$ yoyoyoyo:/media/sda3/cache/hello-world$ tree-L2-a./ ./ ├── .git │ ├── branches │ ├── config │ ├── description │ ├── HEAD │ ├── hooks │ ├── info │ ├── objects │ └── refs ├── .gitignore ├── main.py ├── pyproject.toml ├── .python-version ├── README.md ├── uv.lock └── .venv ├── bin ├── CACHEDIR.TAG ├── .gitignore ├── lib ├── lib64 -lib ├── .lock └── pyvenv.cfgpyproject.tomlpyproject.toml文件包含项目的元数据[project] name hello-world version 0.1.0 description Add your description here readme README.md requires-python 3.8 dependencies [].python-version.python-version文件包含项目的默认Python版本。.venv.venv目录包含项目的虚拟环境uv将在该目录安装项目依赖项。uv.lockuv.lock是一个跨平台的锁定文件其中包含有关项目依赖项的确切信息。uv.lock是一个人类可读的 TOML 文件但由 uv 管理不应手动编辑。3. 管理依赖项# 添加最新版本$ uvaddrequests# 添加指定版本$ uvaddrequests2.31.0# 从 requirements.txt 添加所有依赖$ uvadd-rrequirements.txt-cconstraints.txt# 移除$ uv remove requests# 升级$ uv lock --upgrade-package requests克隆项目或更新pyproject.toml后运行uv sync指令一键安装所有依赖$ uvsyncuv sync类似于pip install -r requirements.txt它会根据pyproject.toml和uv.lock安装所有依赖确保环境与其他开发者完全一致。如果安装速度慢可以在pyproject.toml中设置国内镜像源[tool.uv]index-urlhttps://pypi.tuna.tsinghua.edu.cn/simple4. 生成/更新锁文件$ uv lock该命令会解析pyproject.toml中的依赖并生成或更新uv.lock文件。uv.lock应该提交到版本库确保团队所有成员使用完全相同的依赖版本。5. 运行脚本uv run是 uv 中非常实用的命令可以无需手动激活虚拟环境直接运行脚本或命令uv 会自动找到并使用正确的环境# 直接运行 Python 脚本$ uv run main.py# 运行项目中的测试$ uv run pytest# 运行任意命令在虚拟环境的上下文中执行$ uv run python-cimport requests; print(requests.__version__)使用uv run相比手动激活环境的优势不会误用错误的 Python 版本也不会忘记激活环境导致包找不到特别适合在 CI/CD 和脚本自动化中使用。例如运行 flask$ uvaddflask $ uv run -- flask run-p3000或者运行一个脚本example.pyimportflaskprint(hello world)$ uv run example.py6. 构建发行版本$ uv build $lsdist/ hello_world-0.1.0-py3-none-any.whl hello_world-0.1.0.tar.gz输出示例$ yoyoyoyo:/media/sda3/cache/hello-world$ uv build Buildingsourcedistribution... running egg_info creating hello_world.egg-info writing hello_world.egg-info/PKG-INFO writing dependency_links to hello_world.egg-info/dependency_links.txt writing top-level names to hello_world.egg-info/top_level.txt writing manifestfilehello_world.egg-info/SOURCES.txtreading manifestfilehello_world.egg-info/SOURCES.txtwriting manifestfilehello_world.egg-info/SOURCES.txtrunning sdist running egg_info writing hello_world.egg-info/PKG-INFO writing dependency_links to hello_world.egg-info/dependency_links.txt writing top-level names to hello_world.egg-info/top_level.txt reading manifestfilehello_world.egg-info/SOURCES.txtwriting manifestfilehello_world.egg-info/SOURCES.txtrunning check creating hello_world-0.1.0 creating hello_world-0.1.0/hello_world.egg-info copying files to hello_world-0.1.0... copying README.md -hello_world-0.1.0 copying main.py -hello_world-0.1.0 copying pyproject.toml -hello_world-0.1.0 copying hello_world.egg-info/PKG-INFO -hello_world-0.1.0/hello_world.egg-info copying hello_world.egg-info/SOURCES.txt -hello_world-0.1.0/hello_world.egg-info copying hello_world.egg-info/dependency_links.txt -hello_world-0.1.0/hello_world.egg-info copying hello_world.egg-info/top_level.txt -hello_world-0.1.0/hello_world.egg-info copying hello_world.egg-info/SOURCES.txt -hello_world-0.1.0/hello_world.egg-info Writing hello_world-0.1.0/setup.cfg Creatingtararchive removinghello_world-0.1.0(and everything under it)Building wheel fromsourcedistribution... running egg_info writing hello_world.egg-info/PKG-INFO writing dependency_links to hello_world.egg-info/dependency_links.txt writing top-level names to hello_world.egg-info/top_level.txt reading manifestfilehello_world.egg-info/SOURCES.txtwriting manifestfilehello_world.egg-info/SOURCES.txtrunning bdist_wheel running build running build_py creating build/lib copying main.py -build/lib running egg_info writing hello_world.egg-info/PKG-INFO writing dependency_links to hello_world.egg-info/dependency_links.txt writing top-level names to hello_world.egg-info/top_level.txt reading manifestfilehello_world.egg-info/SOURCES.txtwriting manifestfilehello_world.egg-info/SOURCES.txtinstalling to build/bdist.linux-x86_64/wheel runninginstallrunning install_lib creating build/bdist.linux-x86_64/wheel copying build/lib/main.py -build/bdist.linux-x86_64/wheel/. running install_egg_info Copying hello_world.egg-info to build/bdist.linux-x86_64/wheel/./hello_world-0.1.0-py3.8.egg-info running install_scripts creating build/bdist.linux-x86_64/wheel/hello_world-0.1.0.dist-info/WHEEL creating/media/sda3/cache/hello-world/dist/.tmp-k3_8cna4/hello_world-0.1.0-py3-none-any.whland addingbuild/bdist.linux-x86_64/wheelto it addingmain.pyaddinghello_world-0.1.0.dist-info/METADATAaddinghello_world-0.1.0.dist-info/WHEELaddinghello_world-0.1.0.dist-info/top_level.txtaddinghello_world-0.1.0.dist-info/RECORDremoving build/bdist.linux-x86_64/wheel Successfully built dist/hello_world-0.1.0.tar.gz Successfully built dist/hello_world-0.1.0-py3-none-any.whl