前言
大家都在宣传 uv 的快（UV：Python 包管理神器 - 比 pip 快 100 倍），不过针对我们实验室可能需要在多个机器之间迁移 Python 环境的情况，uv 复现环境的便利性同样也值得关注。
虽然已经在尽力向同门们推荐使用 uv，但大家对 conda 的依赖还是很深，也不愿意尝试新的工具。
因此还是决定写一篇教程，介绍一下 uv 的使用方法，稍微推动一下实验室环境管理的变革好了。
安装 uv
Windows 上我还是更推荐使用 winget 安装：
CodeBlock Loading...
Linux/macOS 上则可以参考官方文档使用 curl/wget 安装：
CodeBlock Loading...
初始化 uv 环境
如果如果需要初始化一个新项目，可以在你的 workspace 目录下运行：
CodeBlock Loading...
或者需要将已有的 Python 项目迁移到 uv 环境下，可以在项目目录下运行：
CodeBlock Loading...
此时项目目录中会新建下述文件：
CodeBlock Loading...
.git、.gitignore、README.md就不用解释了main.py是一个示例 Python 文件，不需要可以直接删了pyproject.toml是 Python 项目的配置文件里面记录了项目的元数据和依赖等信息，内容大致如下：toml [project] name = "test-project" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.12" dependencies = [].python-version用于指定当前项目的 Python 版本
指定 Python 版本
编辑 pyproject.toml 文件中的 requires-python 字段，指定当前项目所需的 Python 版本，例如：==3.12、>=3.12 等。
然后运行以下命令安装指定版本的 Python：
CodeBlock Loading...
创建虚拟环境
CodeBlock Loading...
此命令会在当前项目目录下创建一个虚拟环境，文件夹为 .venv，之后可以参考其输出信息激活虚拟环境，如：
CodeBlock Loading...
管理项目依赖
基本用法
需要安装新的依赖时，可以使用以下命令：
CodeBlock Loading...
实际上就是将之前 pip install 替换为 uv add 即可，但该命令除了将依赖安装到虚拟环境中，还会自动将依赖信息写入 pyproject.toml 文件中的 dependencies 字段，并且更新 uv.lock 锁文件以确保依赖版本的可复现性。uv.lock 文件不需要手动编辑，但是对环境复现相当重要，不要把它放进 .gitignore 中。
比如说安装 requests 后，pyproject.toml 中只会多一条 requests 依赖，而 uv.lock 中则会详细记录 requests 及其所有子依赖的具体版本信息，使用 uv tree 命令可以查看依赖树：
CodeBlock Loading...
如果不需要某个依赖了，可以使用以下命令将其卸载：
CodeBlock Loading...
尽可能严格使用 uv 命令管理环境，虽然也提供了
uv pip 命令来兼容 pip 的用法，但该命令不会更新 pyproject.toml 和 uv.lock 文件，将导致环境不可复现的问题。镜像源
如果需要换 Pypi 镜像源，可在 pyproject.toml 文件中添加如下内容（以南大镜像源为例）：
CodeBlock Loading...
pip 中的 index-url
部分包会在自己的 PyPI 镜像源上发布，比如 torch 的 pip 安装命令（参见 torch 官方文档）如下：
CodeBlock Loading...
需要参考 Using uv with PyTorch 将下述内容加入 pyproject.toml 文件中：
CodeBlock Loading...
否则将不会安装 CUDA 版本的 torch 和 torchvision，而是安装 CPU 版本。
这里首先定义了一个名为 pytorch-cu130 的索引源，url 指定为上述 torch 文档中给出的 --index-url，不过这里我直接替换为了南大镜像源 https://mirror.nju.edu.cn/pytorch/whl/cu130。
然后在 tool.uv.sources 中指定了 torch 和 torchvision 这两个包需要从该索引源安装（注：marker 指定了仅当操作系统是 Linux 或 Windows 时，才使用 pytorch-cu130 索引。对于其他操作系统，如 macOS，此配置会被忽略，依然使用默认源）。
复现环境
当你需要在另一台机器上复现当前项目的 Python 环境时，只需克隆项目代码后，运行以下命令：
CodeBlock Loading...
如果想要实现在另一个项目中复现相同的环境，则可以复制 pyproject.toml、uv.lock、.python-version 文件到目标项目目录下，更新 pyproject.toml 中的项目信息，然后运行同样的命令：
CodeBlock Loading...
构建和发布包
如果你是在写一个可供其他人安装的 Pypi 包，你还需要考虑哪些依赖是开发时依赖，哪些是运行时依赖，开发依赖需要使用 uv add --dev [package-name] 命令安装。
之后还需要补充 pyproject.toml 文件中的项目信息，比如作者、许可证，以及构建信息等，考虑到搞科研的大部分时候并不会发布包，这里就不展开讲了，可以参考下述内容进行理解：
CodeBlock Loading...
之后即可，使用以下命令构建和发布包：
CodeBlock Loading...
其他实用命令
uv cache clear：清除 uv 缓存，释放其占用的磁盘空间uv tree：查看当前项目的依赖树uv run main.py：等价于激活虚拟环境后运行python main.py，可以用来运行项目中的 Python 脚本uvx [script-name]：运行工具，有些 Python 包会提供命令行工具，可以使用uvx命令运行它们，例如uvx NJUlogin -h。