前言

uv工具的尝鲜使用，尝试把 pip / pipx / poetry / pyenv都换成 uv。

一、uv的安装

步骤	命令	说明
安装 `uv`	Mac：`brew install uv` Win：scoop install main/uv	安装主程序
查看版本	`uv --version`	确认安装成功
初始化项目	`uv init myproject`	创建 Python 项目（生成 `pyproject.toml`）

二、使用uv替代pyenv

操作	命令	说明
查看可用版本	`uv python list`	列出本机和可下载版本
安装指定版本	`uv python install 3.11`	自动下载并安装
安装最新版本	`uv python install`	自动下载并安装
安装多个版本	`uv python install 3.11 3.12`	自动下载并安装
指定版本升级	`uv python upgrade 3.12`	自动下载并安装
升级所有uv管理的python版本	`uv python upgrade`	自动下载并安装
移除已經安裝的 Python	`uv python uninstall`	移除時一定要指定版本，它一样会搜索相符的版本
重新安装python	`uv python install --reinstall`	这将重新安装所有之前安装的 Python 版本，重新安装也可能解决一些 bug
进入指定版本的终端下	python3.12 python3.11	python后需紧跟安装的版本号

注意

在进行虚拟环境创建于激活之前建议删除pyenv，否则在uv激活虚拟环境的时候，会造成python版本的冲突，否则uv安装过的python解释器，还需要pyenv也安装过，才可以激活使用。

三、替代poetry创建项目与管理虚拟环境

操作	命令	说明
初始化项目	`uv init myproject`	创建 Python 项目（生成 `pyproject.toml`，其中的py版本为系统中最新的版本）
指定python版本初始化项目	`uv init myproject --python 3.12`	创建 Python 项目（生成 `pyproject.toml`，其中的py版本为3.12）
创建虚拟环境	`uv venv --python 3.12`	在当前目录创建 `.venv` ，并指定python版本
强制安装基础包	`uv venv --seed`	如pip, setuptools, wheel）
仅更新 seed 包（pip、setuptools 等）	`uv pip install -U pip setuptools wheel`	不想重建环境（推荐）
激活虚拟环境	Mac：`source .venv/bin/activate` Win：`.venv\Scripts\activate`	启用环境
停用虚拟环境	`deactivate`	退出虚拟环境

1. uv初始化项目目录结构介绍

zsh
$ tree -a -L 2
.
├── .git
│   ├── config
│   ├── description
│   ├── HEAD
│   ├── hooks
│   ├── info
│   ├── objects
│   └── refs
├── .gitignore
├── .python-version
├── .venv
│   ├── .gitignore
│   ├── bin
│   ├── CACHEDIR.TAG
│   ├── lib
│   └── pyvenv.cfg
├── main.py
├── pyproject.toml
├── README.md
└── uv.lock

路径	类型	作用（简述）	常见操作 / 命令	注意事项 / 推荐做法
`.python-version`	文件	项目本地 Python 版本指示（通常只包含 `3.13` 这样的版本号）。	`cat .python-version`	推荐提交到仓库，让协作成员自动使用相同 Python 版本。
`.venv/`	目录	项目本地的虚拟环境（由 `uv venv` 或 `python -m venv .venv` 创建）：包含解释器、site-packages、激活脚本等。	激活：`source .venv/bin/activate`（mac/linux）或 `.venv\Scripts\activate`（Windows）	通常不要提交到 git（把它加入 `.gitignore`）。
`main.py`	文件	项目入口示例脚本（你实际项目可能改为 `app.py` 或放到 `src/` 下）	运行：`uv run python main.py` 或激活环境后 `python main.py`	保持轻量、写清楚如何运行（推荐 README 指示）。
`pyproject.toml`	文件	项目元信息与依赖声明（`uv` 会读取并写入这里。	用 `uv add <pkg>` 添加依赖；可手工编辑 `requires-python = ">=3.12,<3.13"`	推荐提交到仓库。用它来声明项目需要哪个 Python 版本和依赖。
`README.md`	文件	项目说明（安装、运行、贡献指南等）	编辑并维护项目运行说明	好的 README 能让合作者快速上手；把 `uv` 的运行/依赖命令写清楚。
`uv.lock`	文件	依赖锁文件（锁定依赖树的精确版本，保证可复现安装）	同步安装：`uv sync`；更新锁：`uv lock` 或 `uv lock --upgrade`	必须提交到仓库，以确保其他开发者/CI 安装到完全相同的依赖。

2. 项目依赖管理

shell
## 添加依赖包（并更新 pyproject.toml 与锁文件）
uv add requests
## 添加开发依赖<pytest>
uv add pytest --dev
## 删除依赖
uv remove <包名>
## 更新所有依赖到最新版本
uv update
## 更新当前项目单个依赖，并不会更新缓存中的依赖
uv update <包名>
## 安装/同步 pyproject.toml 与锁文件的依赖（通常用于初始化项目或协作者同步环境）
uv sync
## 重新生成锁定文件
uv lock
## 导出为 pip 可读的 requirements 文件（用于兼容旧项目或 Docker 构建）
uv export --format requirements.txt
## 展示依赖层级（默认）
uv tree 
## 显示单包依赖结构
uv tree --package requests
## 查看开发依赖树（和uv tree没有区别）
uv tree --group dev

注

uv add的之前若没有uv venv的话，会自动创建虚拟环境，解释版本通常与.python-version文件中的python版本一致。

3. uv的缓存机制

1. 基本概念的理解

uv cache可以理解为“从PyPI下载的过的包的副本”，及uv从仓库把这些包下载后，uv会进行以下操作：

把它们安装到你的虚拟环境的.venv里
同时在全局缓存目录中保存一份副本（默认在C:\Users<用户名>\AppData\Local\uv\cache）
下次再创建虚拟环境uv add安装依赖时，就不用从网上下载了，就可以直接用C:\Users\<用户名>\AppData\Local\uv\cache副本中的包就可以了，瞬间就安装完成。
上述说的瞬间就安装完成，其实是瞬间建立硬链接完成，在windows系统中，其他环境默认通过硬链接（hardlink）来指向缓存目录，这样的好处是：
- 磁盘中只存了一份文件
- 多个虚拟环境共享同一个包内容
- 删除任意一个硬链接都不影响其他的

注意

硬链接有个限制：不能跨盘符，比如缓存目录在 D 盘，而项目在 C 盘，那就没法用硬链接了。这种情况下 uv 会退回到“复制文件”的方式（稍微慢一点，占空间多一点），例：windows系统使用uv add，系统会提示：

shell
(uv-demo) D:\Pycode\uv-demo>uv add requests Resolved 12 packages in 12.65s Prepared 2
packages in 15.19s Uninstalled 2 packages in 25ms ░░░░░░░░░░░░░░░░░░░░ [0/2] Installing 
wheels... 
warning: Failed to hardlink files; falling back to full copy. This may lead 
to degraded performance. If the cache and target directories are on different 
filesystems, hardlinking may not be supported. 
If this is intentional, set export 
UV_LINK_MODE=copy or use --link-mode=copy to suppress this warning.

2. 配置缓存路径

如果你的项目是在盘符D，那么也想将缓存目录也放在D盘：

shell
## 1. 在windows中的高级系统中打开`环境变量`
## 2. 在系统变量中点击【新建】
| 变量名            | 变量值                   |
| -------------- | --------------------- |
| `UV_CACHE_DIR` | `D:\PyCache\uv-cache` |

## 3. 点击确定，重新打开命令行，输入以下命令，验证：
uv cache dir  # 配置成功后，输出：D:\PyCache\uv-cache

3. 配置缓存文件的强制硬链接（可选，因为windows默认）

shell
1. 在系统变量中点击【新建】
| 变量名            | 变量值                   |
| -------------- | --------------------- |
| `UV_LINK_MODE` | `hardlink` |

4. 验证硬链接是否生效

shell
## 1. 在D盘中的PyCode目录下创建一个新的项目或虚拟环境，安装一个包：
uv init uv-cache
cd demo-cache
uv add pytest
## 2. 用 Windows 的内置命令验证硬链接：
fsutil hardlink list .venv\Lib\site-packages\pytest\__init__.py
## >>
\PyCache\uv-cache\archive-v0\OHQkaI69hHtj4RDpzPbnV\pytest\__init__.py  ## 表示成功使用了缓存的硬链接
\Pycode\uv-cache\.venv\Lib\site-packages\pytest\__init__.py

5. 缓存管理常用命令

shell
## 查看缓存目录路径
uv cache dir
## 删除无引用或过期的缓存包（自动去硬链接的项目中去遍历，只删没链接的）
uv cache prune
## 删除所有未使用的缓存条目
uv cache purge
## 彻底清除所有缓存，相当于“重新开始”
uv cache clean

提示

若想更新缓存中的所有包：
uv cache clean && uv sync

四、替代pip：快速安装依赖

shell
## 安装包
uv pip install
## 卸载包
uv pip uninstall
## 输出当前环境的依赖列表（可写入 requirements.txt）
uv pip freeze > requirements.txt
## 查看指定包的详细信息
uv pip show
## 检查依赖冲突
uv pip check

注意

其实 uv pip install 和 uv add 都能“安装依赖”，但它们的使用场景完全不同。

类比角度	解释
`uv pip install`	像是在你的虚拟环境里「安装一个包」——它只是让你当前能用。比如我想临时测试 `requests`。通常在开发环境中临时安装调试包的情况下使用。
`uv add`	像是在「告诉项目」：我需要这个包！它会写入 `pyproject.toml` 并生成锁文件（`uv.lock`）。

四、uv的打包与发布

1. 项目打包

shell
## 打包
uv build

执行后，会在项目根目录生成 dist/ 文件夹：

shell
D:\Pycode\uv-cache\dist
│
├── uv_cache-0.1.0-py3-none-any.whl
└──  uv_cache-0.1.0.tar.gz

2. 项目发布（test.pypi）

token替换为自己的token

shell
uv publish \
  --publish-url https://test.pypi.org/legacy/ \
  --token pypi-test-xxxx-your-token-xxxx

验证是否上传成功： https://test.pypi.org/project/uv-cache/

参考文章

Python 包管理工具 uv 使用教程
 使用 uv 管理 Python 環境
 uv官网