uv必须用官方脚本安装才能启用Python版本管理等核心功能;pip安装仅提供基础包管理,无法使用uv python命令。推荐PowerShell或curl脚本安装,自动配置PATH并支持全功能。

uv 安装不能只用 pip install uv —— 这会绕过它的核心能力,比如自带 Python 版本管理、独立二进制分发和跨环境一致性。 正确安装方式取决于你是否需要「完全脱离现有 Python 环境」,以及后续是否要管理多个 Python 解释器版本。
用官方脚本安装(推荐:零依赖、自动 PATH)
这是最干净的方式,尤其适合新机器、CI/CD 或想避免污染系统 Python 的场景。它下载预编译的 Rust 二进制,不依赖当前是否有 python 或 pip。
- macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh - Windows(PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" - 安装后自动将
uv加入$PATH(Linux/macOS 写入~/.local/bin,Windows 写入%LOCALAPPDATA%\uv\bin) - 验证:
uv --version;升级:uv self update - ⚠️ 坑:如果终端没重启或没重新加载 shell 配置(如
source ~/.zshrc),可能提示command not found
用 pip 安装(仅限已有 Python 环境且不需管理 Python 版本)
适用于已有稳定 Python、只把 uv 当作「更快的 pip + venv 替代品」的轻量使用场景。但它无法调用 uv python install 等关键命令。
- 命令:
pip install uv(建议加镜像:pip install uv -i https://mirrors.aliyun.com/pypi/simple/) - 此时
uv python list会报错:error: The `python` command is not available when uv is installed via pip - 原因:pip 安装的是 Python 包形式的 uv(
uv模块),不是官方发布的独立二进制(uv可执行文件) - 如果你之后想用
uv python install 3.12或uv venv --python 3.12,必须卸载重装为官方二进制版
用包管理器安装(Homebrew / winget / conda)
适合已习惯对应生态的用户,但要注意版本滞后性和路径控制权。
Camoufox 是一个基于 Firefox 构建的开源反检测浏览器,为 Python 自动化工作流程提供强大的指纹注入和反机器人检测规避功能。它与 Playwright 集成,以提供能够绕过现代机器人检测系统的隐身浏览能力。
立即学习“Python免费学习笔记(深入)”;
- Homebrew(macOS/Linux):
brew install uv→ 二进制可用,uv python正常,但更新可能慢半拍 - winget(Windows):
winget install astral.uv→ 通常较新,但需确认是否启用winget upgrade自动更新 - conda(不推荐):
conda install -c conda-forge uv→ 会把 uv 装进当前 conda 环境,且uv python功能受限(conda 环境下 uv 无法管理 conda 提供的 Python) - ⚠️ 坑:Homebrew/winget 安装的 uv 若与手动下载的二进制共存,
which uv可能指向旧版本,建议用uv --version和command -v uv确认实际路径
安装后必须做的三件事
否则你会在后续使用中反复踩坑,尤其是项目初始化和 Python 版本绑定环节。
- 运行
uv python list:确认能否列出可安装的 Python 版本(首次运行会触发下载索引)。若报错或为空,说明安装不完整或网络被拦截 - 试装一个版本:
uv python install 3.11(不用等太久,几秒内应有响应),再执行uv python list看是否出现本地路径标记(如cpython-3.11.11-linux-x86_64-gnu /home/xxx/.local/share/uv/python/...) - 设置国内镜像源(全局或项目级):
uv config set index-url https://mirrors.aliyun.com/pypi/simple/,否则uv add会默认走 pypi.org,超时率高
真正容易被忽略的点是:uv 的「Python 版本管理」能力只存在于官方二进制中,且首次运行 uv python * 命令时才会触发缓存目录初始化。很多人卡在 uv python install 报错,其实只是因为没先跑一次 uv python list 来拉取元数据。

















