一、pipx管理工具1.1 安装 pipx在 Ubuntu / WSL 上可以用两种方式安装推荐第二种官方脚本或第三种pip 安装最新版本并自动配置 PATH。1.1.1、apt 安装最快但版本往往偏旧sudoaptupdatesudoaptinstallpipx# apt 默认把可执行文件装在 /usr/bin/pipx如果只是想临时体验可以这么做但通常 apt 源里的 pipx 版本落后且不会帮你配置用户路径。1.1.2、官方一键脚本最新版 自动配置python3-mpipinstall--userpipx python3-mpipx ensurepath# 把 ~/.local/bin 写进 PATH解释--user把 pipx 安装到~/.local下避免 sudoensurepath会在~/.bashrc、~/.zshrc等文件尾部追加# added by pipx export PATH$HOME/.local/bin:$PATH让之后所有终端都能直接用pipx命令。执行完后重新开一个终端或source ~/.bashrc再试pipx--version1.1.3、纯 pip 手工 PATH万一网络受限python3-mpipinstall--userpipx# 手动把 ~/.local/bin 加到 PATH并重开终端exportPATH$HOME/.local/bin:$PATH把上面 export 语句写进~/.bashrc或~/.zshrc即可。1.2、使用pipx 安装 poetryHatch 生成 pyproject.toml 文件1.2.1 、Poetry最流行的 All-in-One安装pipxinstallpoetry在现有目录里交互式生成poetry init# 逐步问答最后生成 pyproject.toml• 新项目直接poetry new --src mypkg骨架src 目录、tests、pyproject一次到位。后续操作# 安装依赖poetryaddfastapi...# poetry install # 创建虚拟环境并安装依赖# poetry build # 打包 wheel / sdist1.2.2、Hatch官方推荐的新一代工具安装pipxinstallhatch生成项目模板hatch new mypkg会得到mypkg/ ├─ src/mypkg/__init__.py ├─ tests/ └─ pyproject.toml ← 已写好 build-system project 字段依赖管理cdmypkg hatchenvcreate hatch run dev:pytest hatch build以下是关于 Python 管理工具uv和uvx的详细介绍包括核心功能、使用方式及常见命令二、uv与uvx管理工具推荐uv是高性能 Python 包和环境管理工具旨在替代pip、virtualenv、pip-tools等工具。其核心优势包括极速性能依赖解析和包安装速度比pip快 10-100 倍。集成化功能整合虚拟环境管理、依赖锁定、Python 版本管理、工具运行等。轻量级设计自动识别.venv目录无需手动激活环境。uvx是uv tool run的别名用于在隔离环境中临时运行 Python 工具如ruff、black无需全局安装。2.1、安装uv2.1.1 通过独立脚本安装推荐# Linux/macOScurl-LsSfhttps://astral.sh/uv/install.sh|sh# WindowsPowerShellpowershell-cirm https://astral.sh/uv/install.ps1 | iex2.1.2 通过pipx安装pipxinstalluv2.1.3 验证安装uv--version2.2、uv核心功能与命令uv 官方doc注意在uv环境下的pip操作都需要替换为 uv pip使用which pip 就会发现如果仅使用pip 是环境变量中全局的pip2.2.1项目初始化与开发模式第一步创建项目文件夹创建项目的pyproject.toml文件如下推荐这种做法[project]namefastchat_testversion0.1.0requires-python3.11,3.12dependencies[][build-system]requires[hatchling1.17.1]build-backendhatchling.build[tool.hatch.build.targets.wheel]packages[src/fastchat_test]# 参数解释 - name项目的名字 - version项目的版本 - requires-python比较重要如果不指定uv add 时可能会安装最新的python这里强制uv安装指定的python版本 - dependencies项目依赖库使用 uv add 后add 的包会添加至这里 - build-system使用 用 hatch 打包 - tool.hatch.build.targets.wheel指定包目录src-layout 项目,这会让 Hatch 把 src/fastchat_test 当作主包项 目的核心代码也在src/fastchat_test目录下使用 uv pip install -e . 命令后python会以src/fastchat_test作为项目 根目录寻址第二步创建.gitignore和.gitattributes文件内容如下.gitignore# Python-generated files__pycache__/ *.py[oc]build/ dist/ wheels/ *.egg-info# Virtual environments.venv# macOS 系统文件.DS_Store# 包含子目录中的 .DS_Store**/.DS_Store# pycharm .idea.idea/ *.iml# vibe code.claude/ .worktrees/ .agents/ .codex/# 自定义文件draft/.gitattributes# 自动识别文本文件所有文本在工作区统一使用 LF*textautoeollf# Windows 批处理脚本保留 CRLF*.bat texteolcrlf *.cmd texteolcrlf# 明确标记二进制文件禁止行尾转换*.xlsx binary *.xls binary *.png binary *.jpg binary *.jpeg binary *.gif binary *.ico binary *.pdf binary *.zip binary *.gz binary *.tar binary *.pkl binary *.woff binary *.woff2 binary *.ttf binary *.eot binary第三步使用uv add添加包类似pip intall包第四步使用uv remove移除包类似pip uninstall包第五步可能会用到source .venv/bin/activate激活虚拟环境第六步以编辑模式install项目命令为uv pip install -e .注意前面的uv前缀必须加上特别适合项目发布前开发阶段详情可以见 15分钟搞懂Python项目结构和打包由于我们创建的pyproject.toml文件定义了[tool.hatch.build.targets.wheel]故uv pip install -e .后packages对应的路径会加入到python寻址的PATH中卸载使用uv pip uninstall .命令以packages作为项目导包根目录将不会出现导包路径错误第七步打包项目为whl包发布使用uv build或python -m build2.2.2项目依赖安装当拿到他人使用uv管理的项目时只需要执行uv sync即可将整个依赖环境安装# 环境依赖包同步uvsync# 使用下面命令可以将项目以可编辑模式安装到当前目录uv的虚拟环境中uv pipinstall-e.# 仅卸载当前项目推荐uv pip uninstall你的项目包名# 注你的项目包名 是你在 pyproject.toml 或 setup.py 中定义的 name而不是当前的文件夹名。2.2.3常用的简单命令uvsync# 根据 pyproject.toml 同步环境uv pip list# 查看安装的包uv self update# 更新 uv 工具自身uv cache prune# 清理过期缓存如有更新故障2.2.4uv安装包uv pip 与 uv add 的区别用uv add xxx安装包会被写进你的依赖文件团队成员一同步代码就能看到项目需要这个包。用uv pip install xxx只是把包装进当前环境但依赖文件里没有这个包的记录以后别人同步依赖或者清空环境重装时这个包就不会自动被安装需要手动加回。总结“临时”只装进环境、不记录依赖不会自动删除除非你手动卸载或者重新创建环境。如果想试完就删可以自己运行uv pip uninstall xxx如果想安装后自动删除可以写个脚本但uv本身不会自动卸载。拓展举例安装并试用不会记录依赖文件uv pipinstallsomepkg# 用完可以卸载uv pip uninstall somepkg# 从 requirements.txt 安装依赖uv pipinstall-rrequirements.txt# 升级已有包uv pipinstall--upgradeuvicorn# 查看当前安装的包uv pip list# 导出依赖冻结## uv pip freeze requirements.txtuv pip list--formatfreezerequirements.txt# 查看包信息uv pip show fastapi# 清理缓存uv pip cache purge安装并记录到项目推荐团队项目uvaddsomepkg# 会写入 pyproject.toml 或 requirements.txt2.3、uvx工具运行2.3.1、基础用法运行工具uvx ruff.# 运行最新版 Ruffuvx blacklatest# 强制使用最新版uvx ruff0.3.0 check# 指定版本处理包名与命令名不同uvx--fromhttpie http# 包名为 httpie命令为 http2.3.2、高级功能安装额外依赖uvx--withmkdocs-material mkdocs# 包含插件从 Git 源运行uvx--fromgithttps://github.com/httpie/climaster httpie2.3.3、安装工具到全局若需频繁使用某工具可全局安装uv toolinstallruff# 安装到 PATHuv tool upgrade ruff# 升级2.3.4、uv与uvx对比场景uv命令uvx命令运行脚本uv run py文件运行临时工具uv tool run 工具名uvx 工具名指定工具版本uv tool run tool版本uvx tool版本全局安装工具uv tool install不适用包含额外依赖uv tool run --withuvx --with2.3.5、常见问题与注意事项环境隔离uvx默认在临时环境中运行工具与项目依赖隔离。若需访问项目依赖如运行pytest应使用uv run。缓存机制uv缓存依赖以提高性能可通过uv cache clean清理缓存。兼容性uv pip命令兼容传统pip工作流但部分高级功能可能略有差异。三、参考文献使用 uv 管理 Python 環境 Ubuntu / WSL 安装pipx uv 管理项目
一、pipx管理工具1.1 安装 pipx在 Ubuntu / WSL 上可以用两种方式安装推荐第二种官方脚本或第三种pip 安装最新版本并自动配置 PATH。1.1.1、apt 安装最快但版本往往偏旧sudoaptupdatesudoaptinstallpipx# apt 默认把可执行文件装在 /usr/bin/pipx如果只是想临时体验可以这么做但通常 apt 源里的 pipx 版本落后且不会帮你配置用户路径。1.1.2、官方一键脚本最新版 自动配置python3-mpipinstall--userpipx python3-mpipx ensurepath# 把 ~/.local/bin 写进 PATH解释--user把 pipx 安装到~/.local下避免 sudoensurepath会在~/.bashrc、~/.zshrc等文件尾部追加# added by pipx export PATH$HOME/.local/bin:$PATH让之后所有终端都能直接用pipx命令。执行完后重新开一个终端或source ~/.bashrc再试pipx--version1.1.3、纯 pip 手工 PATH万一网络受限python3-mpipinstall--userpipx# 手动把 ~/.local/bin 加到 PATH并重开终端exportPATH$HOME/.local/bin:$PATH把上面 export 语句写进~/.bashrc或~/.zshrc即可。1.2、使用pipx 安装 poetryHatch 生成 pyproject.toml 文件1.2.1 、Poetry最流行的 All-in-One安装pipxinstallpoetry在现有目录里交互式生成poetry init# 逐步问答最后生成 pyproject.toml• 新项目直接poetry new --src mypkg骨架src 目录、tests、pyproject一次到位。后续操作# 安装依赖poetryaddfastapi...# poetry install # 创建虚拟环境并安装依赖# poetry build # 打包 wheel / sdist1.2.2、Hatch官方推荐的新一代工具安装pipxinstallhatch生成项目模板hatch new mypkg会得到mypkg/ ├─ src/mypkg/__init__.py ├─ tests/ └─ pyproject.toml ← 已写好 build-system project 字段依赖管理cdmypkg hatchenvcreate hatch run dev:pytest hatch build以下是关于 Python 管理工具uv和uvx的详细介绍包括核心功能、使用方式及常见命令二、uv与uvx管理工具推荐uv是高性能 Python 包和环境管理工具旨在替代pip、virtualenv、pip-tools等工具。其核心优势包括极速性能依赖解析和包安装速度比pip快 10-100 倍。集成化功能整合虚拟环境管理、依赖锁定、Python 版本管理、工具运行等。轻量级设计自动识别.venv目录无需手动激活环境。uvx是uv tool run的别名用于在隔离环境中临时运行 Python 工具如ruff、black无需全局安装。2.1、安装uv2.1.1 通过独立脚本安装推荐# Linux/macOScurl-LsSfhttps://astral.sh/uv/install.sh|sh# WindowsPowerShellpowershell-cirm https://astral.sh/uv/install.ps1 | iex2.1.2 通过pipx安装pipxinstalluv2.1.3 验证安装uv--version2.2、uv核心功能与命令uv 官方doc注意在uv环境下的pip操作都需要替换为 uv pip使用which pip 就会发现如果仅使用pip 是环境变量中全局的pip2.2.1项目初始化与开发模式第一步创建项目文件夹创建项目的pyproject.toml文件如下推荐这种做法[project]namefastchat_testversion0.1.0requires-python3.11,3.12dependencies[][build-system]requires[hatchling1.17.1]build-backendhatchling.build[tool.hatch.build.targets.wheel]packages[src/fastchat_test]# 参数解释 - name项目的名字 - version项目的版本 - requires-python比较重要如果不指定uv add 时可能会安装最新的python这里强制uv安装指定的python版本 - dependencies项目依赖库使用 uv add 后add 的包会添加至这里 - build-system使用 用 hatch 打包 - tool.hatch.build.targets.wheel指定包目录src-layout 项目,这会让 Hatch 把 src/fastchat_test 当作主包项 目的核心代码也在src/fastchat_test目录下使用 uv pip install -e . 命令后python会以src/fastchat_test作为项目 根目录寻址第二步创建.gitignore和.gitattributes文件内容如下.gitignore# Python-generated files__pycache__/ *.py[oc]build/ dist/ wheels/ *.egg-info# Virtual environments.venv# macOS 系统文件.DS_Store# 包含子目录中的 .DS_Store**/.DS_Store# pycharm .idea.idea/ *.iml# vibe code.claude/ .worktrees/ .agents/ .codex/# 自定义文件draft/.gitattributes# 自动识别文本文件所有文本在工作区统一使用 LF*textautoeollf# Windows 批处理脚本保留 CRLF*.bat texteolcrlf *.cmd texteolcrlf# 明确标记二进制文件禁止行尾转换*.xlsx binary *.xls binary *.png binary *.jpg binary *.jpeg binary *.gif binary *.ico binary *.pdf binary *.zip binary *.gz binary *.tar binary *.pkl binary *.woff binary *.woff2 binary *.ttf binary *.eot binary第三步使用uv add添加包类似pip intall包第四步使用uv remove移除包类似pip uninstall包第五步可能会用到source .venv/bin/activate激活虚拟环境第六步以编辑模式install项目命令为uv pip install -e .注意前面的uv前缀必须加上特别适合项目发布前开发阶段详情可以见 15分钟搞懂Python项目结构和打包由于我们创建的pyproject.toml文件定义了[tool.hatch.build.targets.wheel]故uv pip install -e .后packages对应的路径会加入到python寻址的PATH中卸载使用uv pip uninstall .命令以packages作为项目导包根目录将不会出现导包路径错误第七步打包项目为whl包发布使用uv build或python -m build2.2.2项目依赖安装当拿到他人使用uv管理的项目时只需要执行uv sync即可将整个依赖环境安装# 环境依赖包同步uvsync# 使用下面命令可以将项目以可编辑模式安装到当前目录uv的虚拟环境中uv pipinstall-e.# 仅卸载当前项目推荐uv pip uninstall你的项目包名# 注你的项目包名 是你在 pyproject.toml 或 setup.py 中定义的 name而不是当前的文件夹名。2.2.3常用的简单命令uvsync# 根据 pyproject.toml 同步环境uv pip list# 查看安装的包uv self update# 更新 uv 工具自身uv cache prune# 清理过期缓存如有更新故障2.2.4uv安装包uv pip 与 uv add 的区别用uv add xxx安装包会被写进你的依赖文件团队成员一同步代码就能看到项目需要这个包。用uv pip install xxx只是把包装进当前环境但依赖文件里没有这个包的记录以后别人同步依赖或者清空环境重装时这个包就不会自动被安装需要手动加回。总结“临时”只装进环境、不记录依赖不会自动删除除非你手动卸载或者重新创建环境。如果想试完就删可以自己运行uv pip uninstall xxx如果想安装后自动删除可以写个脚本但uv本身不会自动卸载。拓展举例安装并试用不会记录依赖文件uv pipinstallsomepkg# 用完可以卸载uv pip uninstall somepkg# 从 requirements.txt 安装依赖uv pipinstall-rrequirements.txt# 升级已有包uv pipinstall--upgradeuvicorn# 查看当前安装的包uv pip list# 导出依赖冻结## uv pip freeze requirements.txtuv pip list--formatfreezerequirements.txt# 查看包信息uv pip show fastapi# 清理缓存uv pip cache purge安装并记录到项目推荐团队项目uvaddsomepkg# 会写入 pyproject.toml 或 requirements.txt2.3、uvx工具运行2.3.1、基础用法运行工具uvx ruff.# 运行最新版 Ruffuvx blacklatest# 强制使用最新版uvx ruff0.3.0 check# 指定版本处理包名与命令名不同uvx--fromhttpie http# 包名为 httpie命令为 http2.3.2、高级功能安装额外依赖uvx--withmkdocs-material mkdocs# 包含插件从 Git 源运行uvx--fromgithttps://github.com/httpie/climaster httpie2.3.3、安装工具到全局若需频繁使用某工具可全局安装uv toolinstallruff# 安装到 PATHuv tool upgrade ruff# 升级2.3.4、uv与uvx对比场景uv命令uvx命令运行脚本uv run py文件运行临时工具uv tool run 工具名uvx 工具名指定工具版本uv tool run tool版本uvx tool版本全局安装工具uv tool install不适用包含额外依赖uv tool run --withuvx --with2.3.5、常见问题与注意事项环境隔离uvx默认在临时环境中运行工具与项目依赖隔离。若需访问项目依赖如运行pytest应使用uv run。缓存机制uv缓存依赖以提高性能可通过uv cache clean清理缓存。兼容性uv pip命令兼容传统pip工作流但部分高级功能可能略有差异。三、参考文献使用 uv 管理 Python 環境