uv-python包管理工具

一、快速入门

1.安装 uv

支持多种安装方式：

# macOS/Linux（推荐独立安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 如果您的系统没有curl，您可以使用wget:
wget -qO- https://astral.sh/uv/install.sh | sh

通过将特定版本包含在URL中来请求该版本:
curl -LsSf https://astral.sh/uv/0.6.6/install.sh | sh

# Windows（管理员权限运行）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2.第一步

运行 uv 命令 :

(base) moluo@ubuntu:~$ uv
An extremely fast Python package manager.

Usage: uv [OPTIONS] <COMMAND>

Commands:
  run      Run a command or script
  init     Create a new project
  add      Add dependencies to the project
  remove   Remove dependencies from the project
  sync     Update the project's environment
  lock     Update the project's lockfile
  export   Export the project's lockfile to an alternate format
  tree     Display the project's dependency tree
  tool     Run and install commands provided by Python packages
  python   Manage Python versions and installations
  pip      Manage Python packages with a pip-compatible interface
  venv     Create a virtual environment
  build    Build Python packages into source distributions and wheels
  publish  Upload distributions to an index
  cache    Manage uv's cache
  self     Manage the uv executable
  version  Display uv's version
  help     Display documentation for a command

Cache options:
  -n, --no-cache               Avoid reading from or writing to the cache,
                               instead using a temporary directory for the
                               duration of the operation [env: UV_NO_CACHE=]
      --cache-dir <CACHE_DIR>  Path to the cache directory [env: UV_CACHE_DIR=]

Python options:
      --python-preference <PYTHON_PREFERENCE>
          Whether to prefer uv-managed or system Python installations [env:
          UV_PYTHON_PREFERENCE=] [possible values: only-managed, managed,
          system, only-system]
      --no-python-downloads
          Disable automatic downloads of Python. [env:
          "UV_PYTHON_DOWNLOADS=never"]

Global options:
  -q, --quiet
          Do not print any output
  -v, --verbose...
          Use verbose output
      --color <COLOR_CHOICE>
          Control the use of color in output [possible values: auto, always,
          never]
      --native-tls
          Whether to load TLS certificates from the platform's native
          certificate store [env: UV_NATIVE_TLS=]
      --offline
          Disable network access [env: UV_OFFLINE=]
      --allow-insecure-host <ALLOW_INSECURE_HOST>
          Allow insecure connections to a host [env: UV_INSECURE_HOST=]
      --no-progress
          Hide all progress outputs [env: UV_NO_PROGRESS=]
      --directory <DIRECTORY>
          Change to the given directory prior to running the command
      --project <PROJECT>
          Run the command within the given project directory
      --config-file <CONFIG_FILE>
          The path to a `uv.toml` file to use for configuration [env:
          UV_CONFIG_FILE=]
      --no-config
          Avoid discovering configuration files (`pyproject.toml`, `uv.toml`)
          [env: UV_NO_CONFIG=]
  -h, --help
          Display the concise help for this command
  -V, --version
          Display the uv version

Use `uv help` for more details.

你可以得到一个帮助菜单

3.安装python

# 安装最新的Python版本:
uv python install

# 安装特定的Python版本:
uv python install 3.12

# 安装多个Python版本:
uv python install 3.11 3.12

# 安装替代的Python实现，例如PyPy:
uv python install pypy@3.10

查看python安装

# 查看可用和已安装的Python版本:
uv python list

4.运行脚本和声明依赖关系

Python脚本是用于独立执行的文件，例如python <script>.py。使用uv执行脚本可确保无需手动管理环境即可管理脚本依赖性。

# 请注意，如果您使用uv run在一个项目，即带有pyproject.toml，它将在运行脚本之前安装当前项目。如果您的脚本不依赖于项目，请使用--no-project跳过此步骤的标志:

# Note: the `--no-project` flag must be provided _before_ the script name.
uv run --no-project example.py

5.创建处理项目

uv支持管理Python项目，Python项目在pyproject.toml文件。

1.创建新项目

# 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

# 尝试一下uv run:
uv run main.py 

(base) moluo@ubuntu:~/hello-world$ uv run main.py 
Using CPython 3.8.5 interpreter at: /home/moluo/anaconda3/bin/python3.8
Creating virtual environment at: .venv
Hello from hello-world!

2.项目结构

# 一个项目由几个重要的部分组成，这些部分协同工作并允许uv管理您的项目。除了由创建的文件以外uv init，uv将创建一个虚拟环境uv.lock第一次运行项目命令时，文件位于项目的根目录中，即，uv run, uv sync，或者uv lock.

# 完整的清单如下所示:
.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

3.`pyproject.toml`

pyproject.toml

[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []

# 您将使用这个文件来指定依赖项，以及关于项目的细节，比如它的描述或者许可。
# 您可以手动编辑该文件，或者使用如下命令uv add和uv remove从终端管理您的项目。

4.管理依赖关系

# 将依赖项添加到pyproject.toml与uv add命令。这也将更新锁定文件和项目环境:
uv add requests

# 指定版本约束或替代源:
# Specify a version constraint
uv add 'requests==2.31.0'

# Add a git dependency
uv add git+https://github.com/psf/requests

# 删除包
uv remove requests

# 升级包，运行uv lock与--upgrade-package标志:
uv lock --upgrade-package requests
# `--upgrade-package`标志将尝试将指定的包更新到最新的兼容版本，同时保持锁定文件的其余部分不变。

uv add pandas             # 生产环境
uv add --group dev pytest # 开发环境
uv add "flask>=2.0,<3.0"  # 语义化版本控制
uv add --group dev "pytest~=7.4"  # 兼容性版本 (~=7.4 表示 7.4.x)
uv add --group dev "pytest>=7.4,<7.5"  # 精确版本范围
uv add requests numpy pandas  # 一次性添加多个包
uv add -r requirements.txt  # 从现有项目迁移,自动转换格式到 pyproject.toml

# 同步环境
uv sync

此命令根据 pyproject.toml 创建虚拟环境（默认 .venv），并安装所有依赖。当运行 uv sync 时：

1. 解析 pyproject.toml 中的依赖声明

2. 检查本地缓存是否存在预编译的 wheel 包

3. 并行下载缺失的依赖（默认 8 线程）

4. 创建隔离的虚拟环境（使用 POSIX 兼容的 venv 模块）

5. 安装依赖并生成哈希校验的 uv.lock
                        
原文链接：https://blog.csdn.net/sinat_37574187/article/details/145644999

5.运行命令uv run

uv run可用于在您的项目环境中运行任意脚本或命令。

6.uv build

# uv build可用于为您的项目构建源代码发行版和二进制发行版(wheel)。

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

uv build
ls dist/

(hello-world) (base) moluo@ubuntu:~/hello-world$ ls dist/
hello_world-0.1.0-py3-none-any.whl  hello_world-0.1.0.tar.gz

6.构建,发布包

1.为打包准备项目

在尝试发布项目之前，您需要确保它已准备好进行打包以供分发。

如果您的项目不包含[build-system]中的定义pyproject.toml，uv默认不会构建它。这意味着您的项目可能还没有准备好发布。

# 如果您有不想发布的内部包，可以将它们标记为私有:

[project]
classifiers = ["Private :: Do Not Upload"]

# 此设置使PyPI拒绝发布您上传的包。它不会影响替代注册表上的安全或隐私设置。

# 我们还建议只生成每个项目的令牌:如果没有与项目匹配的PyPI令牌，它就不会被意外发布。

2.构建发布包

uv build


uv publish

# 遇到的问题
(hello-world) (base) moluo@ubuntu:~/hello-world$ uv publish
Publishing 2 files https://upload.pypi.org/legacy/
Enter username ('__token__' if using a token): 
Enter password: 
Uploading hello_world-0.1.0-py3-none-any.whl (1.2KiB)
error: Failed to publish `dist/hello_world-0.1.0-py3-none-any.whl` to https://upload.pypi.org/legacy/
  Caused by: Upload failed with status code 403 Forbidden. Server says: 403 Username/Password authentication is no longer supported. Migrate to API Tokens or Trusted Publishers instead. See https://pypi.org/help/#apitoken and https://pypi.org/help/#trusted-publishers

# 解决:
你遇到的错误是由于 PyPI (Python Package Index) 现在不再支持使用用户名和密码直接进行身份验证，取而代之的是使用 **API Tokens** 或 **Trusted Publishers** 进行身份验证。

### 解决方法：

1. **创建 API Token**：
   按照以下步骤生成并使用 API Token 来上传包：

   - 访问 [PyPI 官网](https://pypi.org/) 并登录你的账户。
   - 进入你的 **Account settings** 页面：[https://pypi.org/manage/account/](https://pypi.org/manage/account/)
   - 在 "API Tokens" 部分点击 "Add API token"。
   - 选择合适的权限，通常选择 "Entire account" 或 "Specific project"。
   - 生成并复制新的 **API Token**。

2. **使用 API Token 上传包**：
   - 在终端中，使用 API Token 作为用户名来进行身份验证，而不是你的 PyPI 密码。
   - 在你输入用户名时，输入 `__token__`，然后在密码提示时粘贴你刚刚生成的 API Token。

   例如：
   ```bash
   Enter username ('__token__' if using a token): __token__
   Enter password: <Your API Token>
   ```

3. **重新上传**：
   之后你应该能够成功上传你的包。

### 额外说明：
- **API Token** 提供了一种更安全的认证方式，因为它是可以单独撤销的，避免了直接暴露密码的风险。
- 如果你不希望每次上传都输入 Token，可以将它配置在 `.pypirc` 配置文件中，使其自动使用。

例如，你可以在 `~/.pypirc` 文件中配置如下：
```ini
[distutils]
index-servers =
    pypi

[pypi]
username = __token__
password = <Your API Token>
```

这样就可以避免每次上传时输入 Token。

7.作为工具运行和安装应用程序

1.运行工具

# 运行ruff:
uvx ruff

# 这完全等同于:
uv tool run ruff
# uvx为方便起见，作为别名提供。

2.安装工具

如果经常使用某个工具，将它安装到持久环境中并将其添加到PATH而不是调用uvx反反复复。

# 安装ruff
uv tool install ruff

# 升级工具
uv tool upgrade ruff

# 升级所有
uv tool upgrade --all

二.进阶功能

1.python版本管理

uv 支持安装和管理多版本 Python：

uv python install 3.11    # 安装指定版本
uv python list            # 查看已安装版本
uv python pin 3.11        # 固定项目使用的 Python 版本

2.虚拟环境高级配置

• 自定义虚拟环境路径：
uv venv --python /path/to/python myenv
• 全局缓存优化：uv 使用全局缓存加速重复安装，可通过 uv cache dir 查看缓存路径。

3.依赖锁定与升级

• 生成锁文件：
uv lock
• 选择性升级依赖：
uv lock --upgrade-package requests

4.工具管理（uv tool 与 uvx）

uv 提供了两种管理命令行工具的方式：uv tool 和 uvx，它们都用于在隔离环境中安装和运行 Python 工具。

4.1 uv tool 命令

#uv tool 类似于 pipx，用于在隔离环境中安装和管理 Python 命令行工具：

#安装工具

uv tool install ruff                 # 安装最新版本
uv tool install "black==23.12.1"     # 安装特定版本
uv tool install "pylint>=2.17.0"     # 使用版本约束

#运行工具

uv tool run ruff check .             # 运行已安装的工具
uv tool run -i https://mirrors.aliyun.com/pypi/simple black .  # 使用自定义参数

#管理工具

uv tool list                         # 列出所有已安装的工具
uv tool uninstall ruff              # 卸载工具
uv tool upgrade ruff                # 升级工具
uv tool upgrade-all                 # 升级所有工具
特点：

• 每个工具都安装在独立的虚拟环境中

• 自动处理依赖关系

• 支持版本管理和升级

• 可以通过 --system-packages 选项访问系统 Python 包

4.2 uvx 命令
uvx 是一个轻量级替代方案，适合一次性运行或临时使用的场景：

# 直接运行工具（无需预先安装）

uvx ruff check .                   # 自动下载并运行最新版本
uvx black@23.12.1 .                # 运行特定版本
uvx "pylint>=2.17.0" ./src         # 使用版本约束

# 运行带参数的命令

uvx pytest --verbose tests/        # 传递参数给工具
uvx black --line-length=100 .      # 设置工具配置

#高级用法

uvx httpie --help         # 直接运行工具并查看帮助
uvx --python=3.9 mypy .   # 指定 Python 版本
特点：

• 即用即走，不需要预安装

• 自动缓存下载的包

• 每次运行都使用临时虚拟环境

• 支持指定多个依赖包

4.3 选择建议

• 使用 uv tool 当：

    • 需要频繁使用某个工具

    • 希望管理工具版本

    • 需要在多个项目间共享工具

• 使用 uvx 当：

    • 想要快速试用某个工具

    • 需要一次性运行

    • CI/CD 环境中的临时任务

4.4 性能优化

# 预热缓存以提升后续运行速度
uv pip install ruff black pylint

# 设置缓存目录
export UV_CACHE_DIR=~/.cache/uv   # Unix
set UV_CACHE_DIR=%LOCALAPPDATA%\uv # Windows

5.多环境与工作区

• 区分开发/生产环境：

pyproject.toml
[dependency-groups]
dev = ["pytest"]
production = ["gunicorn"]

• 工作区支持：多包项目可在同一仓库中共享依赖配置。

6.CI/CD 集成

uv 在持续集成环境中表现优异：

GitHub Actions 示例

steps:
-uses:actions/checkout@v4
-name:Installuv
    run:curl-LsSfhttps://astral.sh/uv/install.sh|sh
-name:Setupenvironment
    run:|
      uv venv
      uv sync
-name:Runtests
    run:uvrun pytest

7.性能优化技巧

• 并行安装：uv 默认启用并行下载和安装

• 缓存预热：在 CI 环境中可预先缓存常用包

uv pip install --cache-dir .cache pandas numpy

四、与 Conda 的整合
若需多版本 Python 支持（uv 暂不支持直接安装 Python），可结合 Conda：

1. 用 Conda 创建基础环境：
   conda create -n py311 python=3.11
2. 在 uv 中指定 Python 解释器：
   uv venv --python $(conda run -n py311 which python) .venv
   此方案兼顾灵活性与性能。

五、最佳实践

优先使用 pyproject.toml：替代 requirements.txt，标准化项目配置。
定期同步环境：在团队协作中通过 uv sync 确保环境一致性。
利用全局缓存：减少重复下载，提升 CI/CD 效率。
版本控制建议：

.venv/
__pycache__/
*.pyc

• 将 uv.lock 纳入版本控制

• 排除 .venv 目录

• 建议的 .gitignore:

项目模板化：
创建标准化的项目结构模板：

myproject/
├── pyproject.toml
├── uv.lock
├── src/
├── tests/
└── docs/

三、常见问题

• 依赖冲突：uv 的解析器会自动处理多数冲突，复杂情况需手动调整版本约束。

• 镜像源配置：在 ~/.config/uv/uv.toml 中设置 index-url 加速下载。

• 与 Conda 冲突：避免同时激活 Conda 和 uv 虚拟环境。

• 性能调优：

• 使用 UV_CACHE_DIR 环境变量自定义缓存位置

• 通过 UV_NO_CACHE=1 禁用缓存（调试时有用）

• 故障排除：

uv --version        # 检查 uv 版本
uv --help          # 查看帮助文档
uv --verbose sync  # 详细日志输出

结语
uv 凭借其极速和一体化设计，正逐步成为 Python 开发者的新选择。无论是小型脚本还是大型项目，它都能显著提升开发效率。未来随着功能迭代（如原生多版本 Python 支持），其生态潜力将更加强大。

原文链接：https://blog.csdn.net/sinat_37574187/article/details/145644999
原文链接: https://docs.astral.sh/uv/

posted @ 2025-03-14 13:03 劉半仙阅读(1409) 评论(0) 收藏举报

刷新页面返回顶部

Bxbg

uv-python包管理工具

一、快速入门

1.安装 uv

2.第一步

3.安装python

查看python安装

4.运行脚本和声明依赖关系

5.创建处理项目

1.创建新项目

2.项目结构

3.`pyproject.toml`

4.管理依赖关系

5.运行命令uv run

6.uv build

6.构建,发布包

1.为打包准备项目

2.构建发布包

7.作为工具运行和安装应用程序

1.运行工具

2.安装工具

二.进阶功能

1.python版本管理

2.虚拟环境高级配置

3.依赖锁定与升级

4.工具管理（uv tool 与 uvx）

5.多环境与工作区

6.CI/CD 集成

7.性能优化技巧

三、常见问题

公告

Bxbg

uv-python包管理工具

一、快速入门

1.安装 uv

2.第一步

3.安装python

查看python安装

4.运行脚本和声明依赖关系

5.创建处理项目

1.创建新项目

2.项目结构

3.pyproject.toml

4.管理依赖关系

5.运行命令uv run

6.uv build

6.构建,发布包

1.为打包准备项目

2.构建发布包

7.作为工具运行和安装应用程序

1.运行工具

2.安装工具

二.进阶功能

1.python版本管理

2.虚拟环境高级配置

3.依赖锁定与升级

4.工具管理（uv tool 与 uvx）

5.多环境与工作区

6.CI/CD 集成

7.性能优化技巧

三、常见问题

公告

3.`pyproject.toml`