一、uv 是什么uv 是 Astral 用 Rust 开发的一体化 Python 工具链一站式替代pip venv pyenv pipx poetry pip-tools twine核心优势速度极快比 pip/Poetry 快 10–100 倍并行下载、全局缓存、高性能 SAT 依赖解析器单二进制文件无 Python 依赖跨平台Windows/macOS/Linux原生管理多 Python 版本、虚拟环境、项目依赖、全局 CLI 工具、打包发布完全兼容 PEP 621 标准pyproject.toml兼容requirements.txt统一锁文件uv.lock可复现环境内置安全漏洞扫描二、安装 uv全平台1. Linux /macOS推荐# 官方一键安装curl-LsSfhttps://astral.sh/uv/install.sh|sh# 指定版本安装示例0.7.14curl-LsSfhttps://astral.sh/uv/0.7.14/install.sh|sh# 刷新环境变量source~/.bashrc# zsh 用户source~/.zshrc2. WindowsPowerShell 管理员Set-ExecutionPolicy Bypass-ScopeProcess -Force;irm https://astral.sh/uv/install.ps1|iex3. 备用pip 安装已有 Python 环境pipinstalluv# 国内加速pipinstalluv-ihttps://pypi.tuna.tsinghua.edu.cn/simple4. 验证安装uv--version# 输出示例uv 0.7.145. 卸载 uv# Linux/macOSrm-rf~/.cargo/bin/uv ~/.cache/uv# WindowsRemove-Item$env:APPDATA\astral\uv-Recurse三、基础全局配置国内镜像 / 代理 / 缓存1. 配置 PyPI 国内镜像必配方式 1环境变量临时终端生效# Linux/macOSexportUV_DEFAULT_INDEXhttps://pypi.tuna.tsinghua.edu.cn/simple# Windows PowerShell$env:UV_DEFAULT_INDEXhttps://pypi.tuna.tsinghua.edu.cn/simple方式 2永久写入 shell 配置推荐# bashechoexport UV_DEFAULT_INDEXhttps://pypi.tuna.tsinghua.edu.cn/simple~/.bashrcsource~/.bashrc# zshechoexport UV_DEFAULT_INDEXhttps://pypi.tuna.tsinghua.edu.cn/simple~/.zshrcsource~/.zshrc方式 3项目内pyproject.toml局部镜像[tool.uv] default-index https://pypi.tuna.tsinghua.edu.cn/simple常用镜像源清华https://pypi.tuna.tsinghua.edu.cn/simple阿里https://mirrors.aliyun.com/pypi/simple中科大https://pypi.mirrors.ustc.edu.cn/simple2. 代理配置# http/https 代理exportUV_PROXYhttp://127.0.0.1:7890# socks5 代理exportUV_PROXYsocks5://127.0.0.1:78903. 缓存目录自定义exportUV_CACHE_DIR~/.uv-cache4. shell 自动补全# bashuv generate-shell-completionbash~/.bash_completion# zshuv generate-shell-completionzsh~/.zsh/completions/_uv# powershelluv generate-shell-completion powershell$PROFILE四、Python 版本管理替代 pyenvuv 内置 Python 二进制分发无需系统预装 Python。1. 查看可安装 Python 版本uv python list# 只看已本地安装uv python list --only-installed2. 安装指定 Python# 安装最新 3.12uv pythoninstall3.12# 批量安装多版本uv pythoninstall3.113.123.13# 强制重装uv pythoninstall--reinstall3.123. 项目锁定 Python 版本生成 .python-version# 当前项目固定使用3.12uv python pin3.12# 查看项目锁定版本cat.python-version4. 卸载 Pythonuv python uninstall3.115. 查找系统 /uv 管理的 Python 解释器uv pythonfind3.12# 输出解释器绝对路径五、虚拟环境管理替代 venv/virtualenv1. 创建虚拟环境# 默认在当前目录生成 .venv使用项目锁定Pythonuv venv# 指定目录、指定Python版本uv venv myenv--python3.12# 启用字节码编译容器/发布加速启动uv venv --compile-bytecode2. 激活 / 退出虚拟环境# Linux/macOSsource.venv/bin/activate# Windows cmd.venv\Scripts\activate.bat# Windows PowerShell.venv\Scripts\Activate.ps1# 退出deactivate3. 无需激活直接运行uv run 核心特性绝大多数场景不需要手动激活 venvuv 自动识别目录下.venvuv run python main.py uv run pytest uv run uvicorn main:app4. 删除虚拟环境rm-rf.venv# 或 uv 命令清理uv clean六、标准项目工作流替代 Poetry/PDM完整工程管理1. 初始化新项目# 创建项目目录并初始化uv init my-democdmy-demo# 初始化时直接指定Python版本uv init fastapi-demo--python3.12生成目录结构plaintextmy-demo/ ├── pyproject.toml# PEP621 项目元信息、依赖配置├── uv.lock# 精确锁文件必须提交Git├── .python-version# 锁定Python版本├── README.md └── main.py2. pyproject.toml 基础结构说明[project] name my-demo version 0.1.0 dependencies [] # 生产依赖 requires-python 3.12 [project.optional-dependencies] # 可选附加依赖组 all [pandas, numpy] [dependency-groups] # 开发依赖组dev为内置特殊组 dev [pytest, ruff, mypy] [tool.uv] default-index https://pypi.tuna.tsinghua.edu.cn/simple3. 依赖增删改查核心命令 uv add /uv remove添加生产依赖# 最新版本uvaddrequests# 指定版本约束uvaddnumpy2.0,2.3# 带附加功能 extrasuvadduvicorn[standard]# 本地路径包uvadd./my-local-lib# Git仓库包uvaddgithttps://github.com/xxx/xxx.git添加开发依赖测试 / 格式化 / 类型检查uvadd--devpytest ruff mypy httpx# 自定义依赖组uvadd--grouplint black isort批量从 requirements.txt 导入依赖uvadd-rrequirements.txt删除依赖uv remove numpy# 删除开发依赖uv remove--devpytest# 删除自定义组依赖uv remove--grouplint black4. 依赖锁定 环境同步团队协作核心生成 / 更新 uv.lock# 自动解析所有依赖生成精确锁文件含版本哈希uv lock# 仅升级单个包其余保持锁定uv lock --upgrade-package numpy# 全部依赖升级到兼容最新版uv lock--upgrade根据锁文件同步环境团队 / CI 统一环境# 安装所有生产开发依赖uvsync# 只装生产依赖线上部署uvsync--no-dev# 严格遵循lock不允许版本浮动CI推荐uvsync--frozen# 同步并自动清理多余包uvsync--clean规范uv.lock必须提交 Git保证所有人、CI 环境完全一致。5. 查看依赖树、冲突排查# 完整依赖树uv tree# 只显示顶级依赖uv tree--depth1# 查找某个包被谁依赖uv tree requests6. 导出依赖为 requirements.txt兼容旧流水线# 导出生产依赖uvexport-orequirements.txt# 导出含开发依赖uvexport--dev-orequirements-dev.txt7. 依赖漏洞安全扫描# 扫描当前锁文件漏洞uv audit七、兼容 pip 传统工作流uv pip 子命令如果你不想用pyproject.toml只想替代 pip用uv pip完全兼容原有脚本# 等价 pip installuv pipinstallrequests uv pipinstall-rrequirements.txt# 等价 pip listuv pip list# 过时包检查uv pip list--outdated# 等价 pip freezeuv pip freezerequirements.txt# 卸载uv pip uninstall requests-y# 检查依赖冲突uv pip check八、全局 CLI 工具管理替代 pipxuv tool install全局隔离安装命令行工具# 全局安装 ruff、blackuv toolinstallruff black# 指定版本uv toolinstallpylint3.2.0临时单次运行工具无需全局安装uvx# 临时执行自动创建临时环境uvx ruff check.uvx--python3.12mycli-tool工具管理# 列出所有全局工具uv tool list# 升级全局工具uv tool upgrade ruff# 卸载uv tool uninstall ruff九、脚本单文件依赖无需项目 pyproject.tomluv 支持在 Python 脚本头部声明依赖一键运行demo.py# /// script# requires-python 3.12# dependencies [requests2.31.0]# ///importrequestsprint(requests.get(https://www.baidu.com).status_code)直接运行自动下载依赖、临时环境运行uv run demo.py十、打包 发布 Python 包替代 setuptools twine1. 构建分发包生成 dist/wheel sdist运行uv build# 仅构建 wheeluv build--wheel# 仅构建源码包uv build--sdist输出目录dist/.whl二进制 wheel推荐安装.tar.gz源码分发包2. 发布到 PyPI / TestPyPI前往 PyPI 官网生成 API Token发布命令# 正式 PyPIuv publish--tokenpypi-xxx-token# 测试源 TestPyPIuv publish--indextestpypi--tokentest-token十一、工作区多包单体仓库 monorepo适用于一个仓库多个子包根目录 pyproject.toml[tool.uv.workspace] members [packages/*] exclude [packages/template]常用工作区命令# 批量给所有子包添加依赖uvadd--workspacerequests# 批量同步全部子包环境uvsync--workspace# 批量运行测试uv run--workspacepytest十二、CI/CD 标准模板GitHub Actionsjobs:test:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-name:Install uvrun:curl-LsSf https://astral.sh/uv/install.sh|sh-name:缓存依赖uses:actions/cachev4 withpath:~/.cache/uvkey:uv-{{hashFiles(uv.lock)}}-name:安装依赖run:uv sync--frozen--dev-name:运行测试run:uv run pytest十三、Docker 最佳实践分层缓存加速FROM python:3.12-slim # 安装 uv COPY --fromghcr.io/astral-sh/uv:latest /uv /bin/uv # 缓存依赖层 WORKDIR /app COPY pyproject.toml uv.lock ./ RUN uv sync --frozen --no-dev # 拷贝源码 COPY . . # 使用 uv run 启动 CMD [uv, run, uvicorn, main:app, --host, 0.0.0.0]十四、高频常用命令速查表项目管理命令功能uv init新建项目uv add pkg添加生产依赖uv add --dev pkg添加开发依赖uv remove pkg删除依赖uv lock更新锁文件uv sync同步虚拟环境uv run cmd在项目环境执行命令uv tree查看依赖树uv audit安全漏洞扫描uv export导出 requirements.txtPython 虚拟环境命令功能uv python list查看可用 Pythonuv python install 3.12安装指定 Pythonuv python pin 3.12项目锁定 Pythonuv venv创建 .venvuv clean清理缓存 / 无用环境工具与打包发布命令功能uv tool install xxx全局安装 CLI 工具uvx xxx临时运行工具uv build构建 wheel/sdistuv publish发布到 PyPIpip 兼容接口命令等价 pipuv pip installpip installuv pip listpip listuv pip freezepip freezeuv pip checkpip check十五、常见问题与避坑国内下载慢务必配置UV_DEFAULT_INDEX清华镜像提交 Git 忽略文件gitignore.venv/ __pycache__/ *.pyc dist/ *.egg-infouv.lock不要忽略必须提交线上部署uv sync --no-dev --frozen只装生产依赖禁止开发包上线Windows PowerShell 执行策略报错使用管理员终端执行安装脚本依赖冲突用uv tree pkgname定位冲突来源uv audit检查安全风险和 conda 混用优先用 uv 管理纯 Python 包conda 仅用于 C/C 系统库CUDA、MKL 等十六、uv vs pip / Poetry 简要对比特性uvpipvenvPoetry语言RustPythonPython解析速度极快慢较慢Python 版本管理内置无需 pyenv无需 pyenv全局 CLI 工具uv tool / uvx无需 pipx无锁文件uv.lock 跨平台无poetry.lock单文件脚本依赖支持不支持不支持monorepo 工作区原生支持无有限支持打包发布内置 build/publish需 setuptools/twine内置
一、uv 是什么uv 是 Astral 用 Rust 开发的一体化 Python 工具链一站式替代pip venv pyenv pipx poetry pip-tools twine核心优势速度极快比 pip/Poetry 快 10–100 倍并行下载、全局缓存、高性能 SAT 依赖解析器单二进制文件无 Python 依赖跨平台Windows/macOS/Linux原生管理多 Python 版本、虚拟环境、项目依赖、全局 CLI 工具、打包发布完全兼容 PEP 621 标准pyproject.toml兼容requirements.txt统一锁文件uv.lock可复现环境内置安全漏洞扫描二、安装 uv全平台1. Linux /macOS推荐# 官方一键安装curl-LsSfhttps://astral.sh/uv/install.sh|sh# 指定版本安装示例0.7.14curl-LsSfhttps://astral.sh/uv/0.7.14/install.sh|sh# 刷新环境变量source~/.bashrc# zsh 用户source~/.zshrc2. WindowsPowerShell 管理员Set-ExecutionPolicy Bypass-ScopeProcess -Force;irm https://astral.sh/uv/install.ps1|iex3. 备用pip 安装已有 Python 环境pipinstalluv# 国内加速pipinstalluv-ihttps://pypi.tuna.tsinghua.edu.cn/simple4. 验证安装uv--version# 输出示例uv 0.7.145. 卸载 uv# Linux/macOSrm-rf~/.cargo/bin/uv ~/.cache/uv# WindowsRemove-Item$env:APPDATA\astral\uv-Recurse三、基础全局配置国内镜像 / 代理 / 缓存1. 配置 PyPI 国内镜像必配方式 1环境变量临时终端生效# Linux/macOSexportUV_DEFAULT_INDEXhttps://pypi.tuna.tsinghua.edu.cn/simple# Windows PowerShell$env:UV_DEFAULT_INDEXhttps://pypi.tuna.tsinghua.edu.cn/simple方式 2永久写入 shell 配置推荐# bashechoexport UV_DEFAULT_INDEXhttps://pypi.tuna.tsinghua.edu.cn/simple~/.bashrcsource~/.bashrc# zshechoexport UV_DEFAULT_INDEXhttps://pypi.tuna.tsinghua.edu.cn/simple~/.zshrcsource~/.zshrc方式 3项目内pyproject.toml局部镜像[tool.uv] default-index https://pypi.tuna.tsinghua.edu.cn/simple常用镜像源清华https://pypi.tuna.tsinghua.edu.cn/simple阿里https://mirrors.aliyun.com/pypi/simple中科大https://pypi.mirrors.ustc.edu.cn/simple2. 代理配置# http/https 代理exportUV_PROXYhttp://127.0.0.1:7890# socks5 代理exportUV_PROXYsocks5://127.0.0.1:78903. 缓存目录自定义exportUV_CACHE_DIR~/.uv-cache4. shell 自动补全# bashuv generate-shell-completionbash~/.bash_completion# zshuv generate-shell-completionzsh~/.zsh/completions/_uv# powershelluv generate-shell-completion powershell$PROFILE四、Python 版本管理替代 pyenvuv 内置 Python 二进制分发无需系统预装 Python。1. 查看可安装 Python 版本uv python list# 只看已本地安装uv python list --only-installed2. 安装指定 Python# 安装最新 3.12uv pythoninstall3.12# 批量安装多版本uv pythoninstall3.113.123.13# 强制重装uv pythoninstall--reinstall3.123. 项目锁定 Python 版本生成 .python-version# 当前项目固定使用3.12uv python pin3.12# 查看项目锁定版本cat.python-version4. 卸载 Pythonuv python uninstall3.115. 查找系统 /uv 管理的 Python 解释器uv pythonfind3.12# 输出解释器绝对路径五、虚拟环境管理替代 venv/virtualenv1. 创建虚拟环境# 默认在当前目录生成 .venv使用项目锁定Pythonuv venv# 指定目录、指定Python版本uv venv myenv--python3.12# 启用字节码编译容器/发布加速启动uv venv --compile-bytecode2. 激活 / 退出虚拟环境# Linux/macOSsource.venv/bin/activate# Windows cmd.venv\Scripts\activate.bat# Windows PowerShell.venv\Scripts\Activate.ps1# 退出deactivate3. 无需激活直接运行uv run 核心特性绝大多数场景不需要手动激活 venvuv 自动识别目录下.venvuv run python main.py uv run pytest uv run uvicorn main:app4. 删除虚拟环境rm-rf.venv# 或 uv 命令清理uv clean六、标准项目工作流替代 Poetry/PDM完整工程管理1. 初始化新项目# 创建项目目录并初始化uv init my-democdmy-demo# 初始化时直接指定Python版本uv init fastapi-demo--python3.12生成目录结构plaintextmy-demo/ ├── pyproject.toml# PEP621 项目元信息、依赖配置├── uv.lock# 精确锁文件必须提交Git├── .python-version# 锁定Python版本├── README.md └── main.py2. pyproject.toml 基础结构说明[project] name my-demo version 0.1.0 dependencies [] # 生产依赖 requires-python 3.12 [project.optional-dependencies] # 可选附加依赖组 all [pandas, numpy] [dependency-groups] # 开发依赖组dev为内置特殊组 dev [pytest, ruff, mypy] [tool.uv] default-index https://pypi.tuna.tsinghua.edu.cn/simple3. 依赖增删改查核心命令 uv add /uv remove添加生产依赖# 最新版本uvaddrequests# 指定版本约束uvaddnumpy2.0,2.3# 带附加功能 extrasuvadduvicorn[standard]# 本地路径包uvadd./my-local-lib# Git仓库包uvaddgithttps://github.com/xxx/xxx.git添加开发依赖测试 / 格式化 / 类型检查uvadd--devpytest ruff mypy httpx# 自定义依赖组uvadd--grouplint black isort批量从 requirements.txt 导入依赖uvadd-rrequirements.txt删除依赖uv remove numpy# 删除开发依赖uv remove--devpytest# 删除自定义组依赖uv remove--grouplint black4. 依赖锁定 环境同步团队协作核心生成 / 更新 uv.lock# 自动解析所有依赖生成精确锁文件含版本哈希uv lock# 仅升级单个包其余保持锁定uv lock --upgrade-package numpy# 全部依赖升级到兼容最新版uv lock--upgrade根据锁文件同步环境团队 / CI 统一环境# 安装所有生产开发依赖uvsync# 只装生产依赖线上部署uvsync--no-dev# 严格遵循lock不允许版本浮动CI推荐uvsync--frozen# 同步并自动清理多余包uvsync--clean规范uv.lock必须提交 Git保证所有人、CI 环境完全一致。5. 查看依赖树、冲突排查# 完整依赖树uv tree# 只显示顶级依赖uv tree--depth1# 查找某个包被谁依赖uv tree requests6. 导出依赖为 requirements.txt兼容旧流水线# 导出生产依赖uvexport-orequirements.txt# 导出含开发依赖uvexport--dev-orequirements-dev.txt7. 依赖漏洞安全扫描# 扫描当前锁文件漏洞uv audit七、兼容 pip 传统工作流uv pip 子命令如果你不想用pyproject.toml只想替代 pip用uv pip完全兼容原有脚本# 等价 pip installuv pipinstallrequests uv pipinstall-rrequirements.txt# 等价 pip listuv pip list# 过时包检查uv pip list--outdated# 等价 pip freezeuv pip freezerequirements.txt# 卸载uv pip uninstall requests-y# 检查依赖冲突uv pip check八、全局 CLI 工具管理替代 pipxuv tool install全局隔离安装命令行工具# 全局安装 ruff、blackuv toolinstallruff black# 指定版本uv toolinstallpylint3.2.0临时单次运行工具无需全局安装uvx# 临时执行自动创建临时环境uvx ruff check.uvx--python3.12mycli-tool工具管理# 列出所有全局工具uv tool list# 升级全局工具uv tool upgrade ruff# 卸载uv tool uninstall ruff九、脚本单文件依赖无需项目 pyproject.tomluv 支持在 Python 脚本头部声明依赖一键运行demo.py# /// script# requires-python 3.12# dependencies [requests2.31.0]# ///importrequestsprint(requests.get(https://www.baidu.com).status_code)直接运行自动下载依赖、临时环境运行uv run demo.py十、打包 发布 Python 包替代 setuptools twine1. 构建分发包生成 dist/wheel sdist运行uv build# 仅构建 wheeluv build--wheel# 仅构建源码包uv build--sdist输出目录dist/.whl二进制 wheel推荐安装.tar.gz源码分发包2. 发布到 PyPI / TestPyPI前往 PyPI 官网生成 API Token发布命令# 正式 PyPIuv publish--tokenpypi-xxx-token# 测试源 TestPyPIuv publish--indextestpypi--tokentest-token十一、工作区多包单体仓库 monorepo适用于一个仓库多个子包根目录 pyproject.toml[tool.uv.workspace] members [packages/*] exclude [packages/template]常用工作区命令# 批量给所有子包添加依赖uvadd--workspacerequests# 批量同步全部子包环境uvsync--workspace# 批量运行测试uv run--workspacepytest十二、CI/CD 标准模板GitHub Actionsjobs:test:runs-on:ubuntu-lateststeps:-uses:actions/checkoutv4-name:Install uvrun:curl-LsSf https://astral.sh/uv/install.sh|sh-name:缓存依赖uses:actions/cachev4 withpath:~/.cache/uvkey:uv-{{hashFiles(uv.lock)}}-name:安装依赖run:uv sync--frozen--dev-name:运行测试run:uv run pytest十三、Docker 最佳实践分层缓存加速FROM python:3.12-slim # 安装 uv COPY --fromghcr.io/astral-sh/uv:latest /uv /bin/uv # 缓存依赖层 WORKDIR /app COPY pyproject.toml uv.lock ./ RUN uv sync --frozen --no-dev # 拷贝源码 COPY . . # 使用 uv run 启动 CMD [uv, run, uvicorn, main:app, --host, 0.0.0.0]十四、高频常用命令速查表项目管理命令功能uv init新建项目uv add pkg添加生产依赖uv add --dev pkg添加开发依赖uv remove pkg删除依赖uv lock更新锁文件uv sync同步虚拟环境uv run cmd在项目环境执行命令uv tree查看依赖树uv audit安全漏洞扫描uv export导出 requirements.txtPython 虚拟环境命令功能uv python list查看可用 Pythonuv python install 3.12安装指定 Pythonuv python pin 3.12项目锁定 Pythonuv venv创建 .venvuv clean清理缓存 / 无用环境工具与打包发布命令功能uv tool install xxx全局安装 CLI 工具uvx xxx临时运行工具uv build构建 wheel/sdistuv publish发布到 PyPIpip 兼容接口命令等价 pipuv pip installpip installuv pip listpip listuv pip freezepip freezeuv pip checkpip check十五、常见问题与避坑国内下载慢务必配置UV_DEFAULT_INDEX清华镜像提交 Git 忽略文件gitignore.venv/ __pycache__/ *.pyc dist/ *.egg-infouv.lock不要忽略必须提交线上部署uv sync --no-dev --frozen只装生产依赖禁止开发包上线Windows PowerShell 执行策略报错使用管理员终端执行安装脚本依赖冲突用uv tree pkgname定位冲突来源uv audit检查安全风险和 conda 混用优先用 uv 管理纯 Python 包conda 仅用于 C/C 系统库CUDA、MKL 等十六、uv vs pip / Poetry 简要对比特性uvpipvenvPoetry语言RustPythonPython解析速度极快慢较慢Python 版本管理内置无需 pyenv无需 pyenv全局 CLI 工具uv tool / uvx无需 pipx无锁文件uv.lock 跨平台无poetry.lock单文件脚本依赖支持不支持不支持monorepo 工作区原生支持无有限支持打包发布内置 build/publish需 setuptools/twine内置
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
