python包管理神器uv使用教程

原创已于 2025-06-11 18:55:50 修改 · 1.3k 阅读

10 ·

CC 4.0 BY-SA版权

文章标签：

#python #人工智能 #开发语言

于 2025-05-07 18:05:04 首次发布

文章目录

uv简介
安装`uv`
管理python
常用命令
示例项目流程
针对项目换源
`uv` 与传统工具的区别
小知识点
- uv run main.py

uv简介

uv 是一个较新的 Python 包管理工具，由 Astral 团队开发，旨在替代 pip、pip-tools、virtualenv 和部分 poetry/pipenv 的功能。它的主要特点是：

🚀 极快的依赖解析和安装速度（用 Rust 编写）
🧩 自动管理虚拟环境
📦 支持锁文件（uv.lock）和传统的 requirements.txt
🧼 统一和简化 Python 项目的依赖管理流程

安装`uv`

pip install uv

管理python

查看可用的python版本

uv python list

(debug) [root@iZj6c6sfmmeac2w0k213fbZ debug]# uv python list
cpython-3.14.0a6-linux-x86_64-gnu                 <download available>
cpython-3.14.0a6+freethreaded-linux-x86_64-gnu    <download available>
cpython-3.13.3-linux-x86_64-gnu                   /root/.local/share/uv/python/cpython-3.13.3-linux-x86_64-gnu/bin/python3.13
cpython-3.13.3+freethreaded-linux-x86_64-gnu      <download available>
cpython-3.12.10-linux-x86_64-gnu                  <download available>
cpython-3.11.12-linux-x86_64-gnu                  <download available>
cpython-3.11.7-linux-x86_64-gnu                   /usr/local/bin/python3.11
cpython-3.11.7-linux-x86_64-gnu                   /usr/local/bin/python3 -> python3.11
cpython-3.10.17-linux-x86_64-gnu                  <download available>
cpython-3.10.0-linux-x86_64-gnu                   /usr/local/bin/python3.10
cpython-3.9.22-linux-x86_64-gnu                   <download available>
cpython-3.8.20-linux-x86_64-gnu                   <download available>
pypy-3.11.11-linux-x86_64-gnu                     <download available>
pypy-3.10.16-linux-x86_64-gnu                     <download available>
pypy-3.9.19-linux-x86_64-gnu                      <download available>
pypy-3.8.16-linux-x86_64-gnu                      <download available>
graalpy-3.11.0-linux-x86_64-gnu                   <download available>
graalpy-3.10.0-linux-x86_64-gnu                   <download available>
graalpy-3.8.5-linux-x86_64-gnu                    <download available>
(debug) [root@iZj6c6sfmmeac2w0k213fbZ debug]#

可以看出uv真的非常强大，它会把各个版本最新的python编译器提供给你，并扫描了你电脑上所有已存在的python编译器，提供给你进行生成虚拟环境使用。对于<download available>的，你可以通过指令进行当即下载，下面会讲到

查看python版本

uv python find

/root/.local/share/uv/python/cpython-3.13.3-linux-x86_64-gnu/bin/python3.13

可以看出查询了当前python路径

uv python find 3.11

/home/debug_amazon_review_spider/.venv/bin/python3

查看指定版本的python路径

uv python find 3.12

error: Failed to inspect Python interpreter from search path at `/usr/bin/python3`
  Caused by: Can't use Python at `/usr/bin/python3`
  Caused by: Python 3.6.8 is not supported. Please use Python 3.8 or newer.

如果不存在则会报异常，从上面uv python list可以看出python3.12是还没安装的

安装指定的python版本

uv python install 3.12

安装完成后查看一下python列表

uv python list

cpython-3.14.0a6-linux-x86_64-gnu                 <download available>
cpython-3.14.0a6+freethreaded-linux-x86_64-gnu    <download available>
cpython-3.13.3-linux-x86_64-gnu                   /root/.local/share/uv/python/cpython-3.13.3-linux-x86_64-gnu/bin/python3.13
cpython-3.13.3+freethreaded-linux-x86_64-gnu      <download available>
cpython-3.12.10-linux-x86_64-gnu                  /root/.local/share/uv/python/cpython-3.12.10-linux-x86_64-gnu/bin/python3.12
cpython-3.11.12-linux-x86_64-gnu                  <download available>
cpython-3.11.7-linux-x86_64-gnu                   /usr/local/bin/python3.11
cpython-3.11.7-linux-x86_64-gnu                   /usr/local/bin/python3 -> python3.11
cpython-3.10.17-linux-x86_64-gnu                  <download available>
cpython-3.10.0-linux-x86_64-gnu                   /usr/local/bin/python3.10
cpython-3.9.22-linux-x86_64-gnu                   <download available>
cpython-3.8.20-linux-x86_64-gnu                   <download available>
pypy-3.11.11-linux-x86_64-gnu                     <download available>
pypy-3.10.16-linux-x86_64-gnu                     <download available>
pypy-3.9.19-linux-x86_64-gnu                      <download available>
pypy-3.8.16-linux-x86_64-gnu                      <download available>
graalpy-3.11.0-linux-x86_64-gnu                   <download available>
graalpy-3.10.0-linux-x86_64-gnu                   <download available>
graalpy-3.8.5-linux-x86_64-gnu                    <download available>

此时可以看出cpython-3.12.10-linux-x86_64-gnu已经被安装到/root/.local/share/uv/python/cpython-3.12.10-linux-x86_64-gnu/bin/python3.12

当然你也可以通过名称来安装指定python版本

uv python install cpython-3.7.9-macos-x86_64-none

同时安装多个python版本

uv python install 3.11 3.12

安装其他的 Python 实现，如 PyPy：

uv python install pypy@3.10

卸载指定 Python 版本

uv python uninstall pypy-3.9.19-linux-x86_64-gnu

设置当前项目固定使用的 Python 版本

uv python pin 3.13

这里有一个很容易混淆的点：你通过uv python pin 3.13指令修改了python版本，他是不会影响系统级别的python版本，所以这里特别强调设置当前项目固定使用的 Python 版本，请看以下指令分析

python -V
Python 3.11.7

uv python find
/home/debug_amazon_review_spider/.venv/bin/python3

uv python pin 3.13
Updated `.python-version` from `3.11` -> `3.13`

python -V
Python 3.11.7

uv python find
/root/.local/share/uv/python/cpython-3.13.3-linux-x86_64-gnu/bin/python3.13

通过python -V指令，我们看到系统直接使用的python是3.11.7版本
查看我们当前uv使用的python（显示的路径python版本是3.11的）
pin指向3.13版本
通过python -V指令，我们看到系统的python版本还是3.11.7，说明系统的python版本是不受影响的
查看我们当前uv使用的python，已经变成了3.13的路径，说明现在uv是指向了3.13版本进行使用

说这么多，它什么意义呢？其实我想说明的重点就是在于，你后面uv venv的时候，uv会在.venv文件夹里生成的python版本，就是你pin后的python版本指定的，所以特此说明

uv python pin特殊说明

特此补充一下，之前理解错误，其实uv是通过目录低下的.python-version来进行版本选择的，也就是说当你直接进入一个目录后，如果有.python-version文件，那么你使用的uv python的指令python的版本号都是以.python-version文件里面的版本号为准

常用命令

操作	命令
初始化项目	`uv init`
创建目录并初始化项目	`uv init project_name`
创建虚拟环境	`uv venv`（自动创建 `.venv`）
激活虚拟环境	Win：`.venv\Scripts\activate` Linux：`source .venv/bin/activate`
删除虚拟环境	删除 `.venv/` 文件夹
安装依赖	`uv pip install requests`
升级依赖	`uv pip install --upgrade requests`
卸载依赖	`uv pip uninstall requests`
冻结依赖	`uv pip freeze > requirements.txt`
使用锁文件安装	`uv pip sync`（读取 `uv.lock`）
生成锁文件	`uv pip compile`（从 `requirements.in`）

添加项目级依赖

uv add flask

pyproject.toml 内容会添加 flask 部分

[project]
name = "01"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "flask>=3.1.0",
]

区别于pip install，uv add会把依赖添加到项目pyproject.toml文件的依赖列表里，当你uv sync的时候将会编译生成到uv.lock里。一般我们对项目强依赖，必须的包，推荐通过uv add进行添加

移除依赖

uv remove flask

查看项目的依赖树

uv tree

导出requirements.txt文件

uv pip compile pyproject.toml -o requirements.txt

推荐：使用这种方式它会只编译pyproject.toml里，你通过uv add xxx添加的依赖包，属于项目强依赖的包，一些开发时临时通过pip install xxx添加的临时包，就不会被编译到其中。这个方法更像通过pip-tools的pip-compile编译后生成的requirements.txt，精简且方便你到时候做成容器

uv pip freeze > requirements.txt

传统方法：前面加上uv确保使用当前目录中的venv环境

示例项目流程

# 1. 初始化项目（创建 venv 和 pyproject.toml）
uv init

# 2. 安装依赖
uv pip install requests flask

# 3. 查看当前依赖
uv pip freeze

# 4. 创建锁文件（类似 pip-tools 的 compile）
uv pip compile

# 5. 后续基于锁文件同步环境
uv pip sync

针对项目换源

在项目文件的pyproject.toml中，添加如下内容：

[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple/"

`uv` 与传统工具的区别

功能	uv	pip/pip-tools	poetry/pipenv
速度	✅ 非常快（Rust）	较慢	中等
虚拟环境管理	✅ 自动	需手动	✅ 自动
支持锁文件	✅ `.lock`	✅（pip-tools）	✅
pyproject.toml 支持	✅	❌	✅

小知识点

uv run main.py

在你来到项目的目录下，跟.venv同个文件夹，直接执行uv run main.py就可以执行你的main.py文件（任意.py文件都可以），而且会直接引用你的虚拟环境，省去你source .venv/bin/activate的步骤，非常方便，重点就是防止了

uv run main.py

有点等同于

source .venv/bin/activate
python main.py