Gavin 的点滴记录

菜单

Administrator
发布于 2026-11-04 / 0 阅读
0
0

软件安装 —— uv

本文适用于 Windows 11 和 CentOS 7。示例以 PowerShell 为主，CentOS 7 的差异在对应小节单独标注。

一、介绍

uv 是用 Rust 编写的 Python 一体化工具，覆盖 Python 版本管理、虚拟环境和包管理。相比传统 pip + venv 组合，它速度更快，并能通过 pyproject.toml 和 uv.lock 保证依赖可复现。

uv 的常用功能可以按使用场景分为三类，分别对应官方文档中的 Projects、Scripts、Tools 板块：

使用场景

命令入口

适用对象

类比

项目（Projects）

uv init / uv add / uv sync

有 pyproject.toml 的工程

poetry / rye

脚本（Scripts）

uv run script.py / uv add --script

单文件脚本

—

工具（Tools）

uvx / uv tool install

运行/安装 CLI 工具

pipx

二、安装 uv

在 PowerShell 中执行官方安装脚本：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后重启终端，运行 uv --version 确认。

如果 PowerShell 阻止脚本执行：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

CentOS：使用官方 shell 脚本安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

三、配置国内镜像

UV_INDEX_URL 影响后续所有包下载，包括 uv python install 下载解释器、uv add / uv sync / uvx 拉取依赖。国内网络建议装完 uv 就先配好，避免后面卡在下载上。

PowerShell：

[Environment]::SetEnvironmentVariable("UV_INDEX_URL", "https://pypi.tuna.tsinghua.edu.cn/simple", "User")

重启终端后生效。

CentOS 7：在 ~/.bashrc 中追加 export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"，然后 source ~/.bashrc。

四、安装 Python

安装最新稳定版：

uv python install

安装指定版本：

uv python install 3.12

查看已安装版本：

uv python list

找一个已安装版本：

uv python find

卸载指定版本：

uv python uninstall 3.12

说明：uv python install 会把解释器安装到 uv 的管理目录，并暴露带版本号的可执行文件（如 python3.12）。默认不会覆盖系统的 python / python3 命令。

五、项目（Projects）：初始化、依赖与环境

项目模式围绕两个文件展开，先建立这个对照，后面的命令才容易理解：

文件

谁维护

作用

是否提交 Git

pyproject.toml

你（或 uv add 自动更新）

声明项目需要什么依赖，版本约束通常是宽松区间

提交

uv.lock

uv 自动生成

记录解析后的精确版本（含传递依赖），保证跨机器复现

提交，但不要手动编辑

日常你只需要改 pyproject.toml（或用 uv add）。uv run / uv sync 会自动检查它和 uv.lock 是否一致，必要时更新锁文件，再把依赖同步到 .venv。想升级依赖时用 uv lock --upgrade 显式更新，不要手改 uv.lock。

项目模式要求当前目录（或父目录）存在 pyproject.toml。首次使用先初始化：

# 初始化项目，生成 pyproject.toml、.python-version、.gitignore 等
uv init example
cd example

# 让现有项目接入 uv，建议用 uv init --bare，只引入 pyproject.toml，不动现有的任何代码结构

1、锁定 Python 版本

# 生成 .python-version，声明项目使用的 Python 版本
uv python pin 3.12

.python-version 应提交到 Git，保证团队和 CI 用同一 Python 版本。它只决定 Python 版本，不创建 pyproject.toml、不安装依赖、不建 .venv。

注意：修改 pin 的版本后，已有的 .venv 不会自动重建以匹配新版本。稳妥做法是删除 .venv 后重新执行 uv run 或 uv sync。

如果不想用 uv python pin，也可以在 pyproject.toml 里用 requires-python 约束版本范围（如 requires-python = "==3.12.*"）。区别在于：pin 是项目级显式锁定，优先级更高，与 requires-python 冲突时会报错；没有 pin 时，requires-python 作为回退依据选择解释器。两者选其一即可，不必同时用。

2、添加依赖

# 安装 ruff 到项目 .venv，并写入 pyproject.toml 和 uv.lock
uv add ruff

uv add 是项目级命令，装到项目 .venv（项目隔离）；而 pip install 装到指定解释器自身（对该解释器全局）。

3、运行命令

# 在项目虚拟环境中运行，无需手动激活
uv run ruff check
uv run python script.py

uv run 会自动找到项目环境并执行命令，不需要手动激活。环境不存在时它会自动创建；依赖有变化时它会先同步再执行。

4、锁定与同步

# 根据 pyproject.toml 重新解析并生成/更新 uv.lock
uv lock

# 根据 uv.lock 同步 .venv（安装缺失依赖、移除多余依赖）
uv sync

# 创建并填充 .venv 是 uv sync（或 uv run）的工作

  • uv lock：只解析依赖、更新锁文件，不安装。

  • uv sync：让 .venv 与锁文件一致，是 CI 和换机后复现环境的推荐命令。

  • uv sync --frozen：严格按现有 uv.lock 安装，不更新锁文件，适合 CI/生产环境。

  • uv lock --upgrade：显式升级依赖并更新锁文件。

三个命令的包含关系：

  • uv run 默认包含 uv sync 的行为（必要时先同步环境再执行），但不删除环境里多余的包。

  • uv sync 默认包含 uv lock 的行为（发现 pyproject.toml 与 uv.lock 不一致时自动更新锁文件），然后精确同步 .venv。

  • uv lock 只更新锁文件，不碰环境。

5、创建环境（通常不需要手动执行）

uv 的项目命令会按需自动管理 .venv，一般不需要手动 uv venv。

手动 uv venv 仅用于：

  • 想在无 pyproject.toml 的目录里快速建一个空隔离环境；

  • 需要非默认名称的环境（如 uv venv myenv），且不想用项目机制。

# 在当前目录创建虚拟环境 .venv（默认约定，主流工具如 VS Code、PyCharm 可自动识别）
uv venv

# 创建名为 myenv 的虚拟环境，适用于临时隔离测试
# 注意：非默认名称 .venv，主流工具可能无法自动识别，需手动指定解释器路径
# uv venv myenv

日常推荐直接用 uv run 自动同步，它已经包含环境准备：

# uv run 会自动确保 .venv 存在且与 uv.lock 一致，再执行命令
uv run python script.py

只有需要单独同步环境、不执行命令时，才单独用：

# 只同步环境，不运行命令
uv sync

六、脚本（Scripts）：非项目目录下的单文件脚本

没有 pyproject.toml 时，uv run 不会自动猜测依赖，需要显式指定。

1、无第三方依赖

# 无依赖时直接用可用 Python 运行；有内联依赖声明时自动创建隔离环境
uv run python script.py

2、有第三方依赖

# 依赖安装在 uv 全局缓存目录。Windows 位置: %LOCALAPPDATA%\uv\cache
# 可用 uv cache dir 查看，用 uv cache prune 清除
uv run --with requests python script.py

3、把依赖写进脚本（PEP 723）

# 在脚本头部插入内联依赖声明，之后直接 uv run script.py 即可
# 依赖位置和 --with 一样。
uv add --script script.py requests

这种方式对脚本文件有轻微侵入（文件头多一段注释），但脚本自包含，发给别人可直接 uv run script.py。

七、工具（Tools）：运行和安装 CLI 工具

工具模式类似 pipx，用于管理 Python 包提供的命令行工具，与项目和脚本环境隔离。

1、临时运行工具：uvx / uv tool run

uvx pycowsay 'hello world!'

uvx 是 uv tool run 的别名，在临时环境中运行工具，不污染全局。输出示例：

  """
  ------------
< hello world! >
  ------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

2、安装工具：uv tool install

uv tool install ruff
ruff --version

安装后工具进入 uv 的工具目录并暴露可执行命令，可长期使用；卸载用 uv tool uninstall ruff。

八、卸载 uv

卸载主程序：

Remove-Item -Force "$env:USERPROFILE\.local\bin\uv.exe" -ErrorAction SilentlyContinue
Remove-Item -Force "$env:USERPROFILE\.local\bin\uvx.exe" -ErrorAction SilentlyContinue

如果通过 WinGet 安装，先尝试：

winget uninstall --id=astral-sh.uv -e

清理数据：

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\uv" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\uv" -ErrorAction SilentlyContinue

如果设置过 UV_INDEX_URL 等环境变量，在“系统属性 → 环境变量”中删除。

验证：uv --version 应提示无法识别。

软件安装 —— fnm

评论