Python 新工具 uv 之快速入门

# 前言

如果你在学习和使用 Python 中，被这些问题困扰过：

pip 安装第三方包时太慢、经常报错
虚拟环境不会用、或容易忘记激活
第三方包版本冲突、换电脑时要重新配置
想快点让程序运行起来，却要折腾半天环境

推荐你试试 uv (opens new window)，这是目前 Python 社区推出的全能工具，由 Astral (opens new window) 软件公司（现已加入 OpenAI）所开发。它使用 Rust 编写，速度比传统工具快 10~100 倍。uv 官方宣称，这是一个非常快速的 Python 编程工具包和项目管理器。它可以用来替代 pip 、 pip-tools 、 pipx 、 poetry 、 pyenv 、 twine 、 virtualenv 等一众工具。

本文面向初学者，教你在“安装 + 运行 + 管理”的开发流程中，学会 uv 的基本使用，全程预计 30 分钟。

# 一、uv是什么？

uv 是 Python 包管理 + 环境管理 + 脚本运行工具，主打极速、极简、零配置。

其特点：

不用手动建立虚拟环境：运行时自动创建
安装包极快：比 pip 快几十倍，几乎秒装
命令极简洁：记住 3~5 条命令，就能覆盖日常需求

使用 uv，你将只需要专注编写 Python 代码，大大降低管理环境的烦恼。

# 二、安装uv

先检查你的环境是否已经安装了 Python。如果没有安装 Python，请选择下面的“一键安装”，这是推荐的安装方式。如果已经安装有 Python，则可以选择“备用安装”。

一键安装（推荐，无需预装 Python）

打开对应的命令行终端，复制执行安装命令：

Linux

以普通用户执行：
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
安装完成后，uv 将默认安装到 $HOME/.local/bin 文件夹内。此文件夹会加入到当前用户的 PATH 环境变量中，需要退出 SSH 并重新登录生效。

Windows（使用 PowerShell）

以普通用户执行，不需要管理员权限：
```
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
安装完成后，uv 将被默认安装到 %HOMEPATH%\.local\bin 文件夹。此文件夹会加入到当前用户的 PATH 环境变量中，需要重新打开一个命令行窗口生效。
备用安装（已有 Python）
```
pip install uv
```
验证安装

安装完成后，通过查看版本来验证安装：
```
# 查看版本
uv --version

# 查看帮助
uv help
```
如果能够显示版本号（如“uv 0.12.15”字样）即表示成功。

升级

当有新版本的时候：

# 在“一键安装”模式中的升级
uv self update

# 在“备用安装”模式中的升级
pip install --upgrade uv

# 升级 uv 管理的 Python 版本
uv python upgrade

卸载

Linux

先清理掉存储的数据（可选）：

# 清理缓存
uv cache clean

# 清理数据文件夹
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

再清理掉 uv 可执行程序：

rm $HOME/.local/bin/uv.exe
rm $HOME/.local/bin/uvx.exe
rm $HOME/.local/bin/uvw.exe

Windows

先清理掉存储的数据（可选）：

# 清理缓存
uv cache clean

# 手动清理下列命令显示的数据文件夹
uv python dir
uv tool dir

再清理掉 uv 可执行程序：

# 手动删除下列文件夹
%HOMEPATH%\.local\bin\uv.exe
%HOMEPATH%\.local\bin\uvx.exe
%HOMEPATH%\.local\bin\uvw.exe

# 三、安装Python

如果你的系统中已经安装了 Python， uv 工具会自动识别并使用现有的 Python 版本，无需进行任何配置。uv 工具也可以安装和管理不同的 Python 版本。在需要时，uv 会自动安装缺失的 Python 版本——因此，在开始使用之前，无需先安装 Python。

安装最新版本的 Python。
```
uv python install
```
注意：
1. 对于 Windows ，上面的 Python 将会被安装到 %APPDATA%\uv\python\ 中。
2. Python 并不发布官方可发行的二进制文件。因此，uv 工具会使用 Astral 项目提供的发行版。
一旦 Python 安装完成， uv 命令就会自动使用该版本。此外，uv 也会将安装后的版本添加到你的 PATH 环境变量中。
安装指定版本的 Python。
```
uv python install 3.12
```
可以同时安装多个 Python 版本：
```
uv python install 3.11 3.12
```
可以卸载某个已安装的版本：
```
uv python uninstall 3.11
```
重新安装 Python。

若要重新安装经过 uv 管理的 Python 版本，可以使用 --reinstall 这样的语法，例如：
```
uv python install --reinstall
```
这将重新安装所有已安装过的 Python 版本。Python 发行版不断有新的改进加入，因此，即使不更改 Python 版本，重新安装也可能解决一些漏洞问题。
查看 Python 的安装情况。

要查看可用的以及安装的 Python 版本：
```
uv python list
```
更多详细信息，可参考 python list 的帮助文档（按q键退出）：
```
uv help python list
```
使用现有的 Python 版本。

如果系统中存在 Python，uv 会使用现有的 Python 版本。对于这种用法，无需进行任何配置：只要系统满足 Python 的要求，uv 就会使用相应的 Python 版本。详情请参阅 Python 发现相关文档。
升级 Python 版本。

要将 Python 版本升级到最新支持的补丁版本：
```
uv python upgrade 3.12
```
要升级所有支持 UV 管理的 Python 版本：
```
uv python upgrade
```
更多详细信息，可参考 python upgrade 的帮助文档（按q键退出）：
```
uv help python upgrade
```

# 四、快速入门

# 4.1 单个脚本

适合：小工具、临时脚本。特点：直接运行，自动处理环境与依赖。

# 案例1：最简单的脚本

创建脚本

新建文件夹（例如 uvtest），在里面创建脚本文件 hello.py，内容如下：
```
# hello.py
print("Hello uv！我是 Python 脚本～")
```
运行脚本

在该文件目录中，打开命令行终端，运行：
```
uv run hello.py
```
屏幕输出示例如下：
```
Hello uv！我是 Python 脚本～
```

# 案例2：带第三方库依赖的脚本

写一个需要用到第三方包的脚本，不用手动安装 pip install 依赖包，uv 会自动安装相关的第三方依赖。

创建脚本

新建文件夹（例如 uvtest），在里面创建脚本文件 demo.py，内容如下：

# demo.py
import requests

res = requests.get("https://www.baidu.com")
print("状态码：", res.status_code)

运行脚本

在该文件目录中，打开命令行终端，运行：
```
uv run demo.py
```
uv 会自动检测并下载依赖包 requests，然后运行脚本。

屏幕输出示例如下：
```
状态码: 200
```

# 4.2 正规项目

适合：正规项目、多文件模块、多人协作。特点： uv 会帮你生成项目的标准文件夹结构，管理依赖、锁定版本。

# 步骤1：创建项目

新建一个项目 “hello-world”，它将创建该项目名称的文件夹。

# 新建项目并初始化
uv init hello-world

# 进入到新建项目的文件夹里面
cd hello-world

与之效果相同的另一种方式是，先创建项目文件夹，再到里面初始化：

# 新建项目文件夹，并进入到里面
mkdir hello-world
cd hello-world

# 再对它进行初始化
uv init

我们可以看到，新建的项目文件夹结构如下所示：

hello_world
    ├── src/
    │   └── hello_world/
    │       └── __init__.py
    ├── README.md
    ├── pyproject.toml          # 项目配置与依赖清单
    ├── .python-version
    └── .gitignore

其中，pyproject.toml 是该项目的配置文件，里面含有项目的重要信息，包括项目名称、版权、依赖、构建等。

# 步骤2：运行项目

在该项目的文件夹中，打开命令行终端，运行：

# 运行项目
uv run hello-world

屏幕输出示例如下：

Hello from hello-world!

# 4.3 常用命令

下面列举一下日常开发工作中， uv 的常见命令。

管理依赖

添加和去除程序的第三方依赖包。

# 添加依赖包
uv add requests

# 去除依赖包
# uv remove requests

管理开发依赖

安装用于开发的第三方依赖包。这些依赖包将不会打包在发行版中，它们仅用于开发环境。
```
# 添加依赖包
uv add --dev pytest ruff

# 去除依赖包
# uv remove --dev ruff
```
上例中，pytest (opens new window) 是一个流行的单元测试工具，ruff (opens new window) 是使用 Rust 编写的 Python 静态代码分析和格式化工具。在 B 站上有2个介绍它们的入门视频：
- 如何使用pytest进行单元测试（12:37） (opens new window)
- Ruff使用指南：最新的超快速代码格式化工具（10:37） (opens new window)
同步全部依赖
```
uv sync
```

运行脚本或项目

# 运行脚本
uv run 脚本文件名.py

# 运行项目
uv run 项目名称

构建

生成发行版压缩包（xxx.tar.gz），输出在 dist 文件夹内。
```
uv build
```

# 五、项目实战

大多数情况下，我们使用 Windows 作为开发环境，部署到服务器上是 Linux 环境。下面将以这样的场景假设，来演示 uv 的使用。

仿照 cowsay (opens new window)，我们来建立一个有趣的 snakesay 项目，它能以下面的 ASCII 卡通蛇图形显示：

$ uv run snakesay hello world

< hello world >
   \    ___
    \  (o o)
        \_/ \
         λ \ \
           _\ \_
          (_____)_
         (________)=Oo°

# 5.1 在Windows上开发

模拟在 Windows 上开发一个 Python 项目 snakesay，设置好开发环境。

创建项目

# 创建项目文件夹，并进入到该文件夹
mkdir snakesay
cd snakesay

# 初始化
uv init

这样，一个项目的初始结构就创建好了。

使用集成开发环境

使用 Visual Stuido Code (opens new window) （下面简称 VSCode）作为 Python 项目的开发环境（也可以选择其他 IDE，如 PyCharm (opens new window) ）。注意，VSCode 本身只是编辑器，它需要安装插件才能作为 Python 的开发环境。具体安装插件的步骤此处从略。
- 用 VSCode 打开项目所在的文件夹，设置为可信任。
- 按快捷键 Ctrl+Shift+P，选择 Python: Select Interpreter 并回车。设置好 Python 解释器。
至此，我们可以使用 VSCode 来进行开发。

添加源代码

在项目文件夹 src\snakesay\ 中，添加源代码文件 snakesay.py，内容如下：

#!/usr/bin/env python
# -*- coding: UTF-8 -*-

import re
import sys
import textwrap
from collections.abc import Iterable

MESSAGE = r"""
{bubble}
   \    ___
    \  (o o)
        \_/ \
         λ \ \
           _\ \_
          (_____)_
         (________)=Oo°
"""


def snakesay(*things) -> str:
    bubble = "\n".join(speech_bubble_lines(" ".join(things)))
    return MESSAGE.format(bubble=bubble)


def speech_bubble_lines(speech) -> Iterable[str]:
    lines, width = rewrap(speech)
    if len(lines) <= 1:
        text = "".join(lines)
        yield f"< {text} >"

    else:
        yield "  " + "_" * width
        yield "/ " + (" " * width) + " \\"
        for line in lines:
            yield f"| {line} |"
        yield "\\ " + (" " * width) + " /"
        yield "  " + "-" * width


def rewrap(speech: str) -> tuple[list[str], int]:
    url_pattern = r"https?://[^\s]+"
    if re.search(url_pattern, speech):
        lines = textwrap.wrap(speech, break_long_words=False, break_on_hyphens=False)
    else:
        lines = textwrap.wrap(speech)
    width = max(len(line) for line in lines) if lines else 0
    return [line.ljust(width) for line in lines], width


def main():  # pragma: no cover
    print(snakesay(*sys.argv[1:]))


if __name__ == "__main__":  # pragma: no cover
    main()

同样的位置，编辑 __init__.py 文件，内容替换如下：

__version__ = "0.1.0"

添加单元测试

在项目文件夹中创建 tests\ 文件夹，用于存放单元测试。在文件夹中添加源文件 test_snakesay.py，内容如下：

#!/usr/bin/env python
# -*- coding: UTF-8 -*-

from snakesay.snakesay import MESSAGE, snakesay


def test_nothing():
    message = snakesay()
    assert message == MESSAGE.format(bubble='<  >')


def test_one_line():
    message = snakesay('hi there')
    assert '< hi there >' in message


def test_two_lines():
    two_lines = 'a' * 81
    message = snakesay(two_lines)
    print(message)
    assert '/ ' in message
    assert '| aaaaa' in message
    assert 'aaaaa |' in message
    assert '\\ ' in message


def test_three_lines():
    three_lines = 'a' * 80 * 2 + 'a'
    long_message = snakesay(three_lines)
    #print(long_message)
    assert '/ ' in long_message
    assert '| aaaaaa' in long_message
    assert 'aaaaaa |' in long_message
    assert '\\ ' in long_message


def test_multiple_arguments():
    message = snakesay('hi', 'there')
    assert '< hi there >' in message


def test_long_url_not_split():
    long_url = 'https://www.example.com/very/long/path/that/exceeds/normal/line/length/and/should/not/be/split/across/multiple/lines'
    message = snakesay(long_url)
    assert long_url in message

    lines = message.split('\n')
    url_containing_lines = [line for line in lines if 'https://' in line]
    assert len(url_containing_lines) == 1, "URL should appear on exactly one line"

添加项目依赖

本项目无外部第三方依赖，仅添加几个用于开发的依赖包：

# 添加项目用于开发的依赖
uv add --dev ruff pytest
uv add --dev coverage pytest-cov

添加版权文件

在项目文件夹内，添加版权文件 LICENSE.txt。这里选择 MIT，内容如下：

MIT License

Copyright (c) 2026

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

修改项目配置

修改项目配置文件 pyproject.toml，适当调整其内容，大致如下：

# Writing your pyproject.toml
# https://packaging.python.org/en/latest/guides/writing-pyproject-toml

[project]
name = "snakesay"
version = "0.1.0"
description = "speaking snake"
authors = [
    { name = "bobyuan", email = "yuan.bob@outlook.com" }
]
license = "MIT"
license-files = ["LICENSE*"]
readme = "README.md"
keywords = ["snakesay"]

requires-python = ">=3.10"
classifiers = [
    # How mature is this project? Common values are
    #   3 - Alpha
    #   4 - Beta
    #   5 - Production/Stable
    "Development Status :: 4 - Beta",

    # Indicate who your project is intended for
    #"Intended Audience :: Developers",
    #"Topic :: Software Development :: Build Tools",

    # Specify the Python versions you support here.
    "Programming Language :: Python :: 3.14",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.10",

    "Operating System :: OS Independent"
]

dependencies = []

[project.scripts]
snakesay = "snakesay.snakesay:main"

[build-system]
requires = ["uv_build>=0.12.15,<0.13.0"]
build-backend = "uv_build"


[dependency-groups]
dev = [
    "coverage>=7.16.2",
    "pytest>=9.1.1",
    "pytest-cov>=7.1.0",
    "ruff>=0.16.8",
]

[tool.pytest.ini_options]
pythonpath = ["src"]
testpaths = ["tests"]

[tool.ruff]
lint.extend-select = ["PTH"]

[tool.coverage.run]
source = ["src/snakesay"]
branch = true

[tool.coverage.report]
show_missing = true

运行单元测试

运行用 pytest 来写的单元测试：

# 单元测试
uv run pytest

# 单元测试，输出更多信息
# uv run pytest -v

检查测试覆盖率

执行单元测试，生成测试覆盖率的 HTML 报告，输出到 htmlcov 文件夹中：

# 检查 src/snakesay，显示没有覆盖的行，输出 HTML 格式的报告
uv run pytest --cov=src/snakesay --cov-report=term-missing --cov-report=html

# 在 Windows 上，用系统默认浏览器打开报告
start htmlcov\index.html

我们需要将这里的 htmlcov 文件夹和 .coverage 文件，都加入到 .gitigore 中。

检查项目

用 ruff 进行代码静态检查和格式化：

# 检查代码
ruff check

# 检查并自动修复发现的问题（仅不破坏功能的修复）
# ruff check --fix

# 格式化代码（缩进、空格等）
ruff format

试运行

# 试运行程序
uv run snakesay Hello, 你好！

屏幕输出示例如下：

&lt; Hello, 你好！ >
   \    ___
    \  (o o)
        \_/ \
         λ \ \
           _\ \_
          (_____)_
         (________)=Oo°

额外检查

请注意，下面这2个都是新引入的实验性特性，可能不稳定，谨慎使用。
```
# 格式化 Python 源文件
uv format

# 检查项目配置
uv check
```
显示项目的依赖
```
# 显示依赖树
uv tree
```
构建

构建生成发行版（输出在 dist 文件夹内）：
```
# 构建项目
uv build
```

本地安装

将这个自己开发的 snakesay 程序，安装到本地系统环境：

# 安装到本地
uv tool install dist\snakesay-0.1.0-py3-none-any.whl

# 反安装
# uv tool uninstall snakesay

重新新打开一个命令行窗口，检查一下，可以直接运行。

# 检查一下
uv tool list

# 直接运行
snakesay hello

屏幕输出示例如下：

C:\Users\bobyuan>uv tool list
snakesay v0.1.0
- snakesay

C:\Users\bobyuan>snakesay hello

< hello >
   \    ___
    \  (o o)
        \_/ \
         λ \ \
           _\ \_
          (_____)_
         (________)=Oo°

# 5.2 在Linux上部署运行

继续上面的例子，通过构建，将在 dist 文件夹内，得到发行版 snakesay-0.1.0.tar.gz 压缩包。将它复制到 Linux 服务器上，解压缩。

# 解压缩
cd ~
tar zxvf ~/Downloads/snakesay-0.1.0.tar.gz

如果 Linux 服务器上已经安装了 uv，则可以直接运行：

# 进入到解压缩的文件夹
cd snakesay-0.1.0

# 运行该项目
uv run snakesay 哈喽，哈喽！

uv 会自动下载依赖并运行，屏幕输出示例如下：

$ uv run snakesay 哈喽，哈喽！

< 哈喽，哈喽！ >
   \    ___
    \  (o o)
        \_/ \
         λ \ \
           _\ \_
          (_____)_
         (________)=Oo°

至此，我们完成了部署和运行。

# 六、命令速查表

整理 uv 最常用命令的速查，如下表：

功能描述	命令	备注
查看命令帮助	`uv help`
查看版本	`uv --version`
升级 uv	`uv self update`
运行某脚本	`uv run 文件名.py`
创建项目	`uv init 项目名`
运行某项目	`uv run 项目名`
运行pytest	`uv run pytest -v`
添加依赖	`uv add 包名`
添加开发时依赖	`uv add --dev 包名`
去除依赖	`uv remove 包名`
同步全部依赖	`uv sync`
格式化Python代码	`uv format`	实验性的新特性
检查项目	`uv check`	实验性的新特性
显示项目的依赖树	`uv tree`
更新项目的锁定文件	`uv lock`
构建	`uv build`
安装到本地系统层级	`uv tool install 包名`
本地系统层级的反安装	`uv tool uninstall 包名`
查看本地系统层级的安装	`uv tool list`

# 七、新手常见问题

问题：运行 uv 时，提示 “uv 不是内部命令” 的错误

可能是在 Windows 上安装后 PATH 环境变量没有生效，建议安装后重新打开一个命令行终端。
问题：需要配置镜像源吗？

不需要。uv 默认速度极快，不用换源。
问题：脚本和项目到底该用哪个？

单文件、练习、小工具：用脚本 Script（uv run xxx.py）。多文件、长期项目、要发布 / 协作：用项目 Project（uv init）

# 八、总结

uv 是 Python 的效率神器，它最大的价值是：接受一套标准项目结构，让你摆脱环境烦恼。

从今天开始，你就可以彻底告别复杂的 pip + venv 组合，用更现代、更快捷、更简单的方式来管理你的 Python 程序环境吧！

最后，B 站上也有一些相关视频介绍，可供参考：

软件谈

Choose mode