Python多版本环境管理UV

1-参考网址

• Python虚拟环境UV管理工具-官网
• Python虚拟环境UV管理工具-快速开始
• pyproject.toml使用指导

---

2-核心知识点

• 1）python项目维护requirements.txt
• 2）python机器学习环境Anaconda
• 3）python轻量级环境管理uv
• 4）uvx快速上手使用

---

3-上手实操

1-安装UV虚拟环境管理工具

• UV官网安装教程

# Windows安装脚本
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"# MacOS和Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

2-Python多版本管理

uv 安装 Python 并允许在版本之间快速切换。

1）安装指定 Python 版本：

# 下载方式1-创建一个环境
uv venv --python 3.12.0# 下载方式2-命令行执行
uv run --python pypy@3.8 -- python# 使用
uv python pin 3.11

---

2）安装多个 Python 版本：

uv python install 3.10 3.11 3.12

3-依赖版本管理

开展项目

uv 支持管理 Python 项目，在文件中定义其依赖关系pyproject.toml。

创建新项目

您可以使用以下命令创建一个新的 Python 项目uv init：

uv init hello-world
cd hello-world

或者，您可以在工作目录中初始化一个项目：

mkdir hello-world
cd hello-world
uv init

uv 将创建以下文件：

.
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

该main.py文件包含一个简单的“Hello world”程序。尝试一下uv run：

uv run main.py

项目结构

项目由几个重要的部分组成，它们协同工作并允许 uv 管理您的项目。除了 创建的文件之外， 当您第一次运行项目命令（即、 或
）时， uv inituv 还会在项目的根目录中创建虚拟环境和文件。uv.lock``uv run``uv sync``uv lock

完整列表如下：

.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

---

Managing dependencies

You can add dependencies to your pyproject.toml with the uv add command. This will also update the lockfile and
project environment:

uv add requests

You can also specify version constraints or alternative sources:

# Specify a version constraint
uv add 'requests==2.31.0'# Add a git dependency
uv add git+https://github.com/psf/requestsxxxxxxxxxx # Specify a version constraintuv add 'requests==2.31.0'# Add a git dependencyuv add git+https://github.com/psf/requestsuv add requests

To remove a package, you can use uv remove:

uv remove requests

To upgrade a package, run uv lock with the --upgrade-package flag:

uv lock --upgrade-package requests

The --upgrade-package flag will attempt to update the specified package to the latest compatible version, while
keeping the rest of the lockfile intact.

See the documentation on managing dependencies for more
details.

Running commands

uv run can be used to run arbitrary scripts or commands in your project environment.

Prior to every uv run invocation, uv will verify that the lockfile is up-to-date with the pyproject.toml, and that
the environment is up-to-date with the lockfile, keeping your project in-sync without the need for manual
intervention. uv run guarantees that your command is run in a consistent, locked environment.

For example, to use flask:

uv add flask
uv run -- flask run -p 3000

Or, to run a script:

example.py

# Require a project dependency
import flaskprint("hello world")

Alternatively, you can use uv sync to manually update the environment then activate it before executing a command:

uv sync
source .venv/bin/activate
flask run -p 3000
python example.py

Note

虚拟环境必须处于活动状态才能在项目中运行脚本和命令uv run。虚拟环境的激活因 shell 和平台而异。

有关更多详细信息，请参阅有关在项目中运行命令和脚本的文档。

构建发行版

uv build可用于为您的项目构建源分布和二进制分布（wheel）。

默认情况下，uv build将在当前目录中构建项目，并将构建的工件放在dist/子目录中：

uv build
ls dist/

---

4-疑惑问答

1. uv 与 pyproject.toml 的关系

理解 uv

uv 通常指的是 ultra-venv，它是一个用于创建和管理 Python 虚拟环境的工具。虚拟环境可以为不同的项目隔离 Python
解释器和依赖包，避免不同项目之间的依赖冲突。

理解 pyproject.toml

pyproject.toml 是 Python 项目的配置文件，在 Python PEP 518
中被引入。它主要用于指定项目的元数据（如项目名称、版本、作者等）以及构建后端（如 setuptools、poetry
等）。通过 pyproject.toml，可以清晰地定义项目的依赖项、构建脚本等信息。

二者关系

• 无直接关系：uv 主要专注于虚拟环境的创建和管理，而 pyproject.toml 是关于项目配置和依赖管理的。它们本身没有直接的功能联系。
• 可间接协同：在一个项目中，你可以使用 uv 创建虚拟环境，然后在这个虚拟环境中根据 pyproject.toml
  里定义的依赖信息来安装项目所需的包。例如，如果你使用 poetry 作为构建后端，poetry 会读取 pyproject.toml
  文件中的依赖列表，然后在 uv 创建的虚拟环境中安装这些依赖。

以下是一个简单示例：

# 使用 uv 创建虚拟环境
uv create my_project_env# 激活虚拟环境
source my_project_env/bin/activate# 在项目根目录下有 pyproject.toml 文件，使用 poetry 安装依赖
poetry install

2. uv的版本管理和 Anaconda 的区别

uv的版本管理

• 专注虚拟环境：uv 主要用于创建和管理 Python 虚拟环境。它可以方便地创建、激活、停用和删除虚拟环境，但对于 Python
  解释器的版本管理功能相对较弱。通常需要手动下载和安装不同版本的 Python 解释器，然后在创建虚拟环境时指定使用哪个版本的解释器。
• 轻量级：uv 是一个轻量级的工具，不会像 Anaconda 那样安装大量的预打包库和工具，因此占用的磁盘空间较小，安装和使用也相对简单。

Anaconda 的版本管理

• 全面的版本管理：Anaconda 是一个集成的 Python 发行版，它不仅可以管理虚拟环境，还可以方便地管理 Python
  解释器的版本。通过 conda 命令，可以轻松地安装、切换不同版本的 Python 解释器，以及安装各种科学计算和数据处理相关的库。
• 丰富的包管理：Anaconda 自带了大量的预打包库，如 NumPy、Pandas、Matplotlib 等。使用 conda
  命令可以方便地安装、更新和卸载这些库，并且可以解决库之间的依赖关系。
• 跨平台支持：Anaconda 支持多种操作系统（如 Windows、Linux、macOS），并且在不同平台上的使用方式基本一致。

区别总结

比较项	uv	Anaconda
功能重点	主要专注于虚拟环境管理	提供全面的 Python 解释器和包版本管理
磁盘占用	轻量级，占用磁盘空间小	安装包较大，占用较多磁盘空间
适用场景	适合简单的 Python 项目，对依赖管理要求不高	适合数据科学、机器学习等需要大量第三方库的项目
包管理	依赖其他工具（如 pip）进行包管理	自带 conda 包管理系统，可管理大量预打包库

---

2-uvx 和 uv是什么关系

uvx (an alias for uv tool run)

1. 基本关系概述

uvx 是 uv 工具运行的别名（an alias for uv tool run）。这意味着 uvx 本质上和使用 uv run
命令的功能是等价的，它是为了方便用户操作而提供的一种快捷方式。

2. 使用方式举例

假设我们有一个 uv 环境，并且想要在这个环境中运行某个 Python 脚本。

使用 uv run

通常情况下，如果使用 uv 自带的 run 命令，我们可能会这样操作：

# 假设我们要运行一个名为 script.py 的 Python 脚本
uv run python script.py

这里的 uv run 命令会在 uv 管理的虚拟环境上下文中执行后面跟着的命令（在这个例子中是 python script.py）。

使用 uvx

而使用 uvx 时，操作会更简洁：

uvx python script.py

这行命令和上面使用 uv run 的命令效果是一样的，都是在 uv 虚拟环境中运行 script.py 脚本。

3. 优势

使用 uvx 作为别名的优势在于减少了输入量，提高了操作效率。特别是对于那些需要频繁在 uv
环境中运行命令的用户来说，每次输入 uv run 可能会比较繁琐，而使用 uvx 可以让命令输入更加简洁、快速。

---