uv 的使用
安装
bash
# mac 推荐
brew install uv
brew upgrade uv
# 安装 & 更新
pip install uv
pip install --upgrade uv
# 安装 & 更新
curl -LsSf https://astral.sh/uv/install.sh | sh
uv self update使用
项目初始化
shell
# 初始化新的项目, 创建 pyproject.toml
uv init example依赖管理
bash
# 安装指定包并添加到依赖（如 uv add requests）
uv add <package>
uv add ruff
# 安装指定版本的包
uv add <package>@<version>
# 安装开发依赖
uv add <package> --dev
# 移除包并从依赖中删除
uv remove <package>
# 语法检测
uv run ruff check
# lock
uv lock
# 列出已安装的依赖
uv list
# 以树形结构展示依赖关系
uv tree
# 查看为什么某个包被安装（依赖来源）
uv pip tree | grep -B 5 -A 5 jmespath
# 查看那些包可以安全升级
# ------------------------------------
# 安装 pip-review
uv add pip-review --dev
# 查看可安全升级的包(这里不要开代理)
pip-review
# 查看可安全升级的包, 仅仅输出包名和版本
pip-review --raw
# 提取可升级的包名并批量升级
pip-review --raw | xargs uv pip install --upgradeUV pip
shell
# 列出所有已安装但存在更新版本的依赖包
uv pip list --outdated
# pip 同步并安装包
vu pip sync requirements.txt
# 升级单个包
uv pip install --upgrade requests
# 批量升级
uv pip list --outdated | awk 'NR>2 {print $1}' | xargs uv pip install --upgrade
# 查看谁依赖了jmespath（使用之前提到的工具）
pipdeptree -r -p jmespath运行
bash
# 运行一个工具
uvx pycowsay 'hello'
# 清理缓存
uv cache clean构建与发布
shell
# 构建项目分发文件（wheel 和 sdist）
uv build
# 将包发布到 PyPI
uv publishpython 版本
bash
# 安装多版本
uv python install 3.10 3.11 3.12
# 当前目录指定 python 版本
uv python pin 3.11环境管理
环境虚拟化
bash
# 创建一个虚拟环境
uv venv
# 指定python 版本虚拟化环境
uv venv --python 3.12.0
# 在虚拟环境中运行命令
uv run pythonQA
使用 uv 从 requirements.txt 迁移到 pyproject.toml
bash
uv init --project .导入 requirements.txt
bash
uv add -r requirements.txt运行并值守项目
bash
# fast api 项目
uv run uvicorn main:app --host 0.0.0.0 --port 8000
# django 项目
uv run gunicorn api.wsgi:application --bind 0.0.0.0:8000uv 使用国内的镜像
uv 加速请求
bash
echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.bashrc
source ~/.bashrc或者单独安装
bash
uv pip install -r pyproject.toml -i https://pypi.tuna.tsinghua.edu.cn/simpleSync
uv sync [OPTIONS]
更新项目环境, 根据 pyproject.toml 和 uv.lock 同步依赖选项
--extra <额外依赖组名>
包含指定额外依赖组中的可选依赖
--output-format <输出格式>
选择输出格式 [默认值: 文本] [可选值: 文本、JSON]
--all-extras
包含所有可选依赖
--no-extra <排除的额外依赖组名>
若指定了`--all-extras`，则排除该参数指定的可选依赖组
--no-dev
禁用开发依赖组 [环境变量: UV_NO_DEV=]
--only-dev
仅包含开发依赖组
--group <依赖组名>
包含指定依赖组中的依赖
--no-group <排除的依赖组名>
禁用指定的依赖组 [环境变量: UV_NO_GROUP=]
--no-default-groups
忽略默认依赖组 [环境变量: UV_NO_DEFAULT_GROUPS=]
--only-group <仅启用的依赖组名>
仅包含指定依赖组中的依赖
--all-groups
包含所有依赖组中的依赖
--no-editable
将所有可编辑依赖（包括当前项目及工作区所有成员）以非可编辑方式安装 [环境变量: UV_NO_EDITABLE=]
--inexact
不删除环境中已存在的无关包
--active
将依赖同步至当前激活的虚拟环境
--no-install-project
不安装当前项目
--no-install-workspace
不安装工作区中的任何成员（包括根项目）
--no-install-local
不安装本地路径依赖
--no-install-package <不安装的包名>
不安装指定的一个/多个包
--locked
确保`uv.lock`文件内容保持不变 [环境变量: UV_LOCKED=]
--frozen
同步依赖时不更新`uv.lock`文件 [环境变量: UV_FROZEN=]
--dry-run
执行空运行（仅模拟操作，不写入锁文件或修改项目环境）
--all-packages
同步工作区中的所有包
--package <指定包名>
仅同步工作区中指定的包
--script <Python脚本路径>
为指定Python脚本同步环境，而非当前项目
--python-platform <Python平台>
安装依赖时适配的目标平台 [可选值: windows、linux、macos、x86_64-pc-windows-msvc、aarch64-pc-windows-msvc、i686-pc-windows-msvc、x86_64-unknown-linux-gnu、aarch64-apple-darwin、x86_64-apple-darwin、aarch64-unknown-linux-gnu、aarch64-unknown-linux-musl、x86_64-unknown-linux-musl、riscv64-unknown-linux、x86_64-manylinux2014、x86_64-manylinux_2_17、x86_64-manylinux_2_28、x86_64-manylinux_2_31、x86_64-manylinux_2_32、x86_64-manylinux_2_33、x86_64-manylinux_2_34、x86_64-manylinux_2_35、x86_64-manylinux_2_36、x86_64-manylinux_2_37、x86_64-manylinux_2_38、x86_64-manylinux_2_39、x86_64-manylinux_2_40、aarch64-manylinux2014、aarch64-manylinux_2_17、aarch64-manylinux_2_28、aarch64-manylinux_2_31、aarch64-manylinux_2_32、aarch64-manylinux_2_33、aarch64-manylinux_2_34、aarch64-manylinux_2_35、aarch64-manylinux_2_36、aarch64-manylinux_2_37、aarch64-manylinux_2_38、aarch64-manylinux_2_39、aarch64-manylinux_2_40、aarch64-linux-android、x86_64-linux-android、wasm32-pyodide2024、arm64-apple-ios、arm64-apple-ios-simulator、x86_64-apple-ios-simulator]
--check
检查Python环境是否与项目依赖同步索引相关选项
--index <索引地址>
解析依赖时使用的额外索引地址（补充默认索引） [环境变量: UV_INDEX=]
--default-index <默认索引地址>
默认包索引的地址（默认值：<https://pypi.org/simple>） [环境变量: UV_DEFAULT_INDEX=]
-i, --index-url <索引地址>
（已废弃：建议使用`--default-index`）Python包索引的地址（默认值：<https://pypi.org/simple>） [环境变量: UV_INDEX_URL=]
--extra-index-url <额外索引地址>
（已废弃：建议使用`--index`）除`--index-url`外额外使用的包索引地址 [环境变量: UV_EXTRA_INDEX_URL=]
-f, --find-links <查找路径>
除注册表索引外，额外的候选分发包查找位置 [环境变量: UV_FIND_LINKS=]
--no-index
忽略注册表索引（如PyPI），仅依赖直接URL依赖和`--find-links`提供的包
--index-strategy <索引策略>
多索引地址解析时采用的策略 [环境变量: UV_INDEX_STRATEGY=] [可选值: first-index（优先首个索引）、unsafe-first-match（不安全-优先匹配项）、unsafe-best-match（不安全-最优匹配项）]
--keyring-provider <密钥环提供方>
尝试使用`keyring`完成索引地址的身份验证 [环境变量: UV_KEYRING_PROVIDER=] [可选值: disabled（禁用）、subprocess（子进程）]解析器相关选项
-U, --upgrade
允许包升级，忽略现有输出文件中的固定版本。隐含`--refresh`
-P, --upgrade-package <待升级包名>
允许指定包升级，忽略现有输出文件中的固定版本。隐含`--refresh-package`
--resolution <版本解析策略>
为给定包依赖选择兼容版本时采用的策略 [环境变量: UV_RESOLUTION=] [可选值: highest（最高版本）、lowest（最低版本）、lowest-direct（最低直接依赖版本）]
--prerelease <预发布版本策略>
处理预发布版本时采用的策略 [环境变量: UV_PRERELEASE=] [可选值: disallow（禁止）、allow（允许）、if-necessary（必要时）、explicit（显式指定时）、if-necessary-or-explicit（必要时或显式指定时）]
--fork-strategy <分支版本策略>
跨Python版本和平台选择同一包的多个版本时采用的策略 [环境变量: UV_FORK_STRATEGY=] [可选值: fewest（最少版本）、requires-python（适配Python版本要求）]
--exclude-newer <截止日期>
仅选择指定日期前上传的候选包 [环境变量: UV_EXCLUDE_NEWER=]
--exclude-newer-package <包名:截止日期>
为指定包限定仅选择截止日期前上传的候选包
--no-sources
解析依赖时忽略`tool.uv.sources`配置表。用于基于标准兼容的、可发布的包元数据生成锁文件，而非使用工作区、Git、URL或本地路径源 [环境变量: UV_NO_SOURCES=]安装器相关选项
--reinstall
重新安装所有包（无论是否已安装）。隐含`--refresh`
--reinstall-package <待重装包名>
重新安装指定包（无论是否已安装）。隐含`--refresh-package`
--link-mode <链接模式>
从全局缓存安装包时采用的方式 [环境变量: UV_LINK_MODE=] [可选值: clone（克隆）、copy（复制）、hardlink（硬链接）、symlink（符号链接）]
--compile-bytecode
安装完成后将Python文件编译为字节码 [环境变量: UV_COMPILE_BYTECODE=]构建相关选项
-C, --config-setting <配置项>
传递给PEP 517构建后端的配置（格式为`键=值`）
--config-settings-package <包名:配置项>
为指定包传递给PEP 517构建后端的配置（格式为`包名:键=值`）
--no-build-isolation
构建源码分发包时禁用隔离环境 [环境变量: UV_NO_BUILD_ISOLATION=]
--no-build-isolation-package <指定包名>
为指定包构建源码分发包时禁用隔离环境
--no-build
不构建源码分发包 [环境变量: UV_NO_BUILD=]
--no-build-package <指定包名>
不为指定包构建源码分发包 [环境变量: UV_NO_BUILD_PACKAGE=]
--no-binary
不安装预构建的wheel包 [环境变量: UV_NO_BINARY=]
--no-binary-package <指定包名>
不为指定包安装预构建的wheel包 [环境变量: UV_NO_BINARY_PACKAGE=]缓存相关选项
-n, --no-cache
不读取/写入缓存，全程使用临时目录 [环境变量: UV_NO_CACHE=]
--cache-dir <缓存目录>
缓存目录的路径 [环境变量: UV_CACHE_DIR=]
--refresh
刷新所有缓存数据
--refresh-package <指定包名>
刷新指定包的缓存数据Python相关选项
-p, --python <Python路径>
项目环境使用的Python解释器路径 [环境变量: UV_PYTHON=]
--managed-python
要求使用uv管理的Python版本 [环境变量: UV_MANAGED_PYTHON=]
--no-managed-python
禁用uv管理的Python版本 [环境变量: UV_NO_MANAGED_PYTHON=]
--no-python-downloads
禁用Python的自动下载功能 [环境变量: "UV_PYTHON_DOWNLOADS=never"]全局选项
-q, --quiet...
启用静默输出模式（多次使用可增强静默程度）
-v, --verbose...
启用详细输出模式（多次使用可增强详细程度）
--color <颜色选项>
控制输出内容的色彩显示 [可选值: auto（自动）、always（始终显示）、never（从不显示）]
--native-tls
是否从平台原生证书库加载TLS证书 [环境变量: UV_NATIVE_TLS=]
--offline
禁用网络访问 [环境变量: UV_OFFLINE=]
--allow-insecure-host <允许不安全的主机>
允许与指定主机建立不安全连接 [环境变量: UV_INSECURE_HOST=]
--no-progress
隐藏所有进度输出 [环境变量: UV_NO_PROGRESS=]
--directory <目录路径>
执行命令前切换到指定目录 [环境变量: UV_WORKING_DIRECTORY=]
--project <项目目录>
在指定项目目录内执行命令 [环境变量: UV_PROJECT=]
--config-file <配置文件路径>
指定要使用的`uv.toml`配置文件路径 [环境变量: UV_CONFIG_FILE=]
--no-config
不自动发现配置文件（`pyproject.toml`、`uv.toml`） [环境变量: UV_NO_CONFIG=]
-h, --help
显示本命令的精简帮助信息