UV常用命令总结

uv是一个用Rust编写的极速Python包和项目管理工具，中文文档可以在这里uv中文文档进行查看，本文会总结一些常用的命令，方便查询

安装UV

使用以下命令安装uv

shell 复制代码

$ curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后进行验证

shell 复制代码

$ uv --version

UV的项目和虚拟环境

uv中，有 项目（project） 和 虚拟环境（venv） 两个概念，两者完全独立、可自由组合，但又默认搭档，第一次接触可能真的分不清楚

项目指的是，只要目录下出现pyproject.toml，uv就把它当项目，项目里只声明要哪些依赖、哪个Python版本，不强制自带venv，依赖版本被uv.lock锁死，确保任何人、任何机器都能复现同一组包

虚拟环境，和Conda 差不多，是一个bin/python+site-packages的目录，完全可脱离项目存在，是一个新的、隔离的python环境

简单来说，项目只管"我要什么"，而venv只管"包在哪里"

项目

初始化项目

初始化一个名称为example的项目

如果不指定项目的python版本，会默认用当前shell中能找到的最新版python，如果项目有python版本要求，需要显式指定

shell 复制代码

# 在当前目录下新建一个名称为example的文件夹作为项目文件夹，并在文件夹中生成项目相关基础文件
$ uv init example
# 已经建好一个目录，进入目录后初始化项目，将项目命名为example
$ uv init -- name example
# 已经建好一个目录，进入目录后初始化项目，项目名称自动命名为当前所在文件夹的名字
$ uv init

# 指定python版本为3.10
$ uv init example --python 3.10        
# 指定python版本的范围
$ uv init example --python ">=3.10,<3.13"

uv init不会创建虚拟环境，因为目前依赖列表是空的，所以也没有uv.lock文件

一键执行

一键执行指令是在刚刚确保好的那个虚拟环境里，把用户给的命令原样exec出去

会确保当前项目有一个最新、且与uv.lock完全对齐的虚拟环境，然后在该环境里运行给定命令

首先，它会找解释器，读取pyproject.toml里的requires-python范围，如果没有指定python版本，按照项目要求选一个用，如果指定了python版本，将指定的版本与项目要求对比，符合要求就执行，不符合就终止运行

shell 复制代码

$ uv run --python 3.10 script.py

其次，它会找虚拟环境，如果.venv已经存在且解释器版本匹配，直接用，如果不存在，会自动创建虚拟环境

最后，它会同步依赖，如果uv.lock不存在，按照pyproject.toml生成lock，如果lock存在但和toml不一致，重新解析并写回lock，如果lock已经最新，按照lock里面的内容将venv里面的包全部对齐，完成环境同步

做完上述步骤后，运行run的内容，会自动激活虚拟环境，但是它是一次性、无提示符的临时激活，只会在它运行的这条命令进程里生效，不会打印最前面的提示符，命令一结束，环境变量就恢复原样，又变回了系统环境

锁定与同步

在uv中，锁定和同步是自动进行的，例如调用uv run，在执行命令之前就会对项目进行锁定和同步

虽然锁文件会自动创建，但也可以显式创建或更新锁文件

shell 复制代码

$ uv lock

虽然环境会自动同步，但也可以显式同步，这条指令就相当于uv run在真正执行用户命令之前进行的全部同步步骤的独立暴露版，进行的事情和上述一样

shell 复制代码

$ uv sync

虚拟环境

显式创建虚拟环境，可以指定python版本，如果指定的版本和pyproject.toml里的requires-python范围不匹配，报错

shell 复制代码

# 创建名为.venv的虚拟环境（默认）
$ uv venv
# 指定python版本
$ uv venv --python 3.12
# 指定虚拟环境名称
$ uv venv myenv --python 3.12

激活虚拟环境，激活后的提示符会显示环境名

shell 复制代码

$ source .venv/bin/activate

激活后，可以使用如下指令进行激活状态验证

shell 复制代码

# 1. 检查 Python 路径
$ which python
# 应该输出：/path/to/your/project/.venv/bin/python

# 2. 检查 pip 路径
$ which pip
# 应该输出：/path/to/your/project/.venv/bin/pip

# 3. 查看已安装的包
$ pip list

# 4. 验证 Python 版本
$ python --version

# 5. 检查环境变量
$ echo $VIRTUAL_ENV
# 应该输出：/path/to/your/project/.venv

退出虚拟环境

shell 复制代码

$ deactivate

更全面的内容，可以看这个网页https://www.cnblogs.com/luckAI/p/18919512

UV安装包

在当前虚拟环境下安装包

用以下指令查看当前pip的路径，如果不是当前虚拟环境的路径，说明使用的是全局的pip ，此时用pip install就会将包安装到全局而不是当前虚拟环境内

shell 复制代码

$ which pip

因此，如果要安装到当前虚拟环境中，最好使用uv的指令，可以在pip前面加上uv，也可以使用uv add

shell 复制代码

$ uv pip install xxx
$ uv add xxx

安装PyTorch

换成国内源，具体的内容参考这个网页https://juejin.cn/post/7582469532328034340

安装好后，使用下面命令可以查看torch的位置，位置应该在当前的虚拟环境中

shell 复制代码

$ uv pip show torch

UV运行

永远显式指定要用哪个python，不要让shell猜，否则容易跳出虚拟环境、装包/运行结果都错

如果.venv不存在，它会当场建好并同步依赖；如果已存在，直接拿.venv/bin/python跑，不会污染系统

shell 复制代码

$ uv run python script.py

强制用.venv/bin/python，不检查lock是否最新，秒启动

shell 复制代码

$ uv run --no-sync python script.py

把解释器写死，绕过shell的PATH，绝对安全

shell 复制代码

$ .venv/bin/python script.py