【自用】uv 管理 Python 环境命令指南

uv 是 Astral 出品的超快 Python 包/项目管理工具Rust 编写可替代 pip、pip-tools、virtualenv、pyenv、poetry 等。下面按使用场景整理常用命令。一、安装 uv# macOS / Linuxcurl-LsSfhttps://astral.sh/uv/install.sh|sh# Windows (PowerShell)powershell-ExecutionPolicyByPass-cirm https://astral.sh/uv/install.ps1 | iex# 或通过 pip 安装pipinstalluv# 验证安装uv--version二、管理 Python 版本替代 pyenvuv pythoninstall3.12# 安装指定 Python 版本uv python list# 查看已安装/可下载的版本uv pythonfind3.12# 查找某版本的路径uv python uninstall3.11# 卸载uv 会按需自动下载 Python无需手动安装。三、创建虚拟环境替代 virtualenvuv venv# 创建 .venv用默认 Pythonuv venv--python3.12# 指定 Python 版本uv venv myenv# 自定义目录名激活uv 本身不需要激活激活只是为了兼容老习惯source.venv/bin/activate# macOS/Linux.venv\Scripts\activate# Windows四、项目管理推荐工作流替代 poetry/pdm初始化项目uv init myproject# 新建项目目录cdmyproject uv init# 在已有目录中初始化uv init--lib# 库项目会生成 src 布局生成文件pyproject.toml、README.md、main.py以及锁定版本的uv.lock。添加 / 移除依赖uvaddrequests# 添加运行时依赖uvaddpytestgt;8# 带版本约束uvadd--devruff# 开发依赖写入 dev groupuvadd--groupdocs mkdocs# 自定义依赖组uv remove requests# 移除依赖uvaddrequests--upgrade# 升级某个包uv lock--upgrade# 升级全部锁定安装与同步环境uvsync# 按 uv.lock 完整同步 .venvuvsync--frozen# CI 中严格按锁文件不重新解析uvsync--no-dev# 只装运行时依赖生产环境运行命令uv run python main.py# 自动使用项目环境运行uv run pytest# 运行依赖的工具无需手动安装uv run --no-sync python x.py# 跳过同步直接运行uv run--withrich python x.py# 临时附加依赖运行其他项目命令uv lock# 生成/更新 uv.lockuv tree# 查看依赖树uv build# 构建 sdist/wheeluv publish# 发布到 PyPIuvexport--formatrequirements-txtgt;requirements.txt# 导出旧格式五、pip 兼容模式低侵入式使用如果已有requirements.txt的项目可直接用uv pipinstall-rrequirements.txt uv pipinstallrequests uv pip list uv pip freeze uv pip uninstall requests uv pip compile requirements.in-orequirements.txt# 替代 pip-tools 注意uv pip需要在虚拟环境中运行或加--system。六、工具运行替代 pipxuvx ruff check# 临时运行 ruff等价 uv tool runuv toolinstallruff# 永久安装某工具到独立环境uv tool list# 查看已安装工具uv tool upgrade ruff# 升级工具uv tool uninstall ruff七、常用全局选项选项说明-p 3.12/--python 3.12指定 Python 版本--directory lt;pathgt;在指定项目目录执行--system操作系统级 Python谨慎使用UV_INDEX_URL换源如国内镜像https://mirrors.aliyun.com/pypi/simple/换源示例写入~/.config/uv/uv.toml[[index]] url https://mirrors.aliyun.com/pypi/simple/ default true八、日常速查流程# 开始一个新项目uv init myappcdmyapp uvaddfastapi uvicorn# 开发uv run uvicorn main:app--reload# 加开发依赖uvadd--devpytest uv run pytest# 团队协作gitaddpyproject.toml uv.lock# 队友拉代码后uvsync# CI 中uvsync--frozenuv run pytest核心记忆点uv add装依赖、uv sync同步环境、uv run跑命令 —— 这三条覆盖 90% 的项目日常uv pip系列兼容旧习惯uvx/uv tool管理命令行工具所有操作都极快比 pip 快 10–100 倍且 uv 会自动管理 Python 版本和虚拟环境。