uv Python 环境管理常用命令

uv 是一个现代化的 Python 包与环境管理工具，特点是解析依赖和安装包都很快。下面整理我日常最常用的一组命令，适合当作速查笔记。

官方文档可以查看：https://docs.astral.sh/uv/

目录

安装与验证

如果只是快速试用，可以直接用 pip 安装：

pip install uv

安装后查看版本：

uv --version

终端能输出版本号，就说明安装成功。

创建虚拟环境

在项目目录下创建一个虚拟环境：

uv venv .venv

激活虚拟环境：

source .venv/bin/activate

Windows PowerShell 下可以使用：

.venv\Scripts\Activate.ps1

退出虚拟环境：

deactivate

安装依赖包

在已激活的虚拟环境中安装依赖：

uv pip install numpy

安装多个包：

uv pip install PySide6 opencv-python

如果需要升级某个包：

uv pip install --upgrade requests

查看当前环境已安装的包：

uv pip list

卸载包：

uv pip uninstall opencv-python

使用镜像源加速

网络不稳定时，可以临时指定镜像源。例如使用清华源：

uv pip install PySide6 opencv-python --index-url https://pypi.tuna.tsinghua.edu.cn/simple

常用参数说明：

• --index-url：指定 Python 包索引地址。
• --upgrade：升级到可解析到的新版。
• --force-reinstall：强制重新安装，适合排查安装损坏或环境异常。

安装到系统环境

如果确实需要把包安装到系统 Python 环境，可以使用 --system：

uv pip install numpy --system

导出和安装 requirements.txt

导出当前环境依赖：

uv pip freeze > requirements.txt

从 requirements.txt 安装依赖：

uv pip install -r requirements.txt

这个模式适合维护已有的 requirements.txt 项目。

使用 uv 项目工作流

如果是新项目，也可以直接使用 uv 的项目工作流：

uv init
uv add requests
uv run python main.py

当项目里存在 pyproject.toml 和锁文件时，可以用下面的命令同步环境：

uv sync

常用排查命令

清理缓存：

uv cache clean

查看 Python 相关信息：

uv python --version

遇到依赖冲突或安装异常时，可以先确认是否激活了正确的虚拟环境，再尝试重新安装：

uv pip install --force-reinstall <package_name>