国内环境如何安装uv

uv 是一个现代的 Python 包安装器和解析器，旨在替代 pip 和 pip-tools。它速度快，并且是使用 Rust 编写的。本教程将指导你在中国大陆的网络环境下安装和使用 uv。

1. 安装 uv

uv 的安装非常简单，你可以通过 pipx 或 curl 命令进行安装。

方案一：使用 pipx (推荐)

pipx 是一个用于安装和运行 Python 应用程序的工具，它会将应用程序安装到隔离的环境中，避免与你的项目依赖冲突。

1. 安装 pipx

   如果你还没有安装 pipx，可以通过 pip 来安装它：

   
   
   
   
   pip install pipx
   
   pipx ensurepath
   

   pipx ensurepath 会将 pipx 的可执行路径添加到你的环境变量中，这样你就可以直接在命令行中使用 pipx 命令了。

2. 安装 uv

   使用 pipx 安装 uv：

   
   
   
   
   
   
   pipx install uv
   

   由于在中国大陆网络环境下载速度可能较慢，或者出现连接超时，你可以尝试配置 pip 的镜像源来加速下载。在安装 pipx 或 uv 时，你可以临时指定镜像源，例如使用阿里云的镜像源：

   
   
   
   
   
   
   pip install pipx -i https://mirrors.aliyun.com/pypi/simple/
   
   pipx install uv --pip-args="--index-url https://mirrors.aliyun.com/pypi/simple/"
   

   如果你希望永久配置 pip 的镜像源，可以创建一个 pip 配置文件。

方案二：使用 curl (适用于没有 Python 环境的情况)

如果你的系统还没有安装 Python，或者你希望通过更直接的方式安装 uv，可以使用 curl 命令下载并安装预编译的二进制文件。

curl -LO https://github.com/astral-sh/uv/releases/latest/download/uv-x86_64-unknown-linux-gnu.tar.gz # Linux

# 或者
curl -LO https://github.com/astral-sh/uv/releases/latest/download/uv-x86_64-apple-darwin.tar.gz # macOS
# 或者
curl -LO https://github.com/astral-sh/uv/releases/latest/download/uv-x86_64-pc-windows-msvc.zip # Windows

下载完成后，你需要手动解压文件，并将 uv 可执行文件添加到你的系统 PATH 环境变量中。

注意： 对于中国大陆网络环境，直接从 GitHub 下载可能会遇到连接问题。你可以尝试使用 VPN 或代理工具，或者通过一些国内的 GitHub 文件加速服务下载。

2. 配置 PyPI 镜像源

为了在中国大陆更流畅地使用 uv 安装 Python 包，强烈建议配置 PyPI 镜像源。uv 会继承 pip 的配置，所以你可以通过配置 pip 的镜像源来实现。

1. 创建或编辑 pip 配置文件

   在你的用户目录下创建或编辑 pip 配置文件：

   • Linux/macOS: ~/.config/pip/pip.conf

   • Windows: %APPDATA%\pip\pip.ini

   如果你不知道 APPDATA 目录在哪里，可以在命令行输入 echo %APPDATA% (Windows) 或 echo $HOME (Linux/macOS) 查看。

2. 添加镜像源配置

   在配置文件中添加以下内容，以使用清华大学的镜像源为例：

   
   
   
   
   
   
   [global]
   
   index-url = https://pypi.tuna.tsinghua.edu.cn/simple
   trusted-host = pypi.tuna.tsinghua.edu.cn
   

   其他常用的镜像源包括：

   • 阿里云：https://mirrors.aliyun.com/pypi/simple/

   • 豆瓣：https://pypi.doubanio.com/simple/

   保存配置文件后，uv 在安装包时就会自动使用你配置的镜像源。

3. uv 的基本使用

uv 的命令与 pip 类似，但更强调性能和一致性。

3.1 创建虚拟环境

使用 uv venv 创建虚拟环境：

uv venv

这会在当前目录下创建一个名为 .venv 的虚拟环境。你也可以指定虚拟环境的名称：

uv venv my_project_env

激活虚拟环境：

• Linux/macOS:

  
  
  
  
  
  
  source .venv/bin/activate
  

• Windows:

  
  
  
  
  
  
  .venv\Scripts\activate
  

3.2 安装包

激活虚拟环境后，使用 uv pip install 安装包：

uv pip install requests

安装多个包：

uv pip install numpy pandas matplotlib

3.3 从 requirements.txt 安装

uv 可以直接从 requirements.txt 文件安装依赖：

uv pip install -r requirements.txt

3.4 升级包

uv pip install --upgrade requests

3.5 卸载包

uv pip uninstall requests

3.6 列出已安装的包

uv pip freeze

3.7 解析和锁定依赖

uv 最强大的功能之一是其快速的依赖解析和锁定能力。它旨在替代 pip-tools。

1. 创建 pyproject.toml

   在你的项目根目录下创建一个 pyproject.toml 文件，并定义你的项目依赖。例如：

   
   
   
   
   
   
   [project]
   
   name = "my-awesome-project"
   version = "0.1.0"
   dependencies = [
       "requests>=2.28",
       "fastapi==0.95.0",
       "uvicorn[standard]>=0.22",
   ]
   

2. 生成锁定文件 (uv.lock)

   使用 uv lock 命令生成一个 uv.lock 文件，其中包含了所有确切的依赖版本：

   
   
   
   
   
   
   uv lock
   

   uv.lock 文件是二进制格式的，不建议手动编辑。

3. 安装锁定文件中的依赖

   在部署或团队协作时，你可以使用 uv sync 命令，根据 uv.lock 文件安装确切的依赖版本，确保环境的一致性：

   
   
   
   
   
   
   uv sync
   

   这会比 pip install -r requirements.txt 更快，并且能保证完全一致的依赖。

4. 常见问题及解决方案 (中国大陆网络环境)

• 下载缓慢或超时：

  • 解决方案： 确保你已经正确配置了 PyPI 镜像源。

  • 解决方案： 尝试更换不同的镜像源，或者在网络状况较好的时间段进行下载。

  • 解决方案： 如果是直接从 GitHub 下载 uv 二进制文件，考虑使用 VPN 或代理工具。

• SSL 证书错误：

  • 解决方案： 有时国内镜像源的 SSL 证书可能不受信任。你可以在 pip 配置文件中添加 trusted-host 选项来信任该主机，例如：

    
    
    
    
    
    
    [global]
    
    index-url = https://pypi.tuna.tsinghua.edu.cn/simple
    trusted-host = pypi.tuna.tsinghua.edu.cn
    

• 命令行报错，提示 uv 命令不存在：

  • 解决方案： 确保 uv 的安装路径已添加到你的系统 PATH 环境变量中。如果你使用的是 pipx 安装，运行 pipx ensurepath。如果你是手动安装的，需要手动配置 PATH。

5. 总结

uv 是一个非常有前景的 Python 包管理工具，它的速度和稳定性将在未来帮助开发者更高效地管理项目依赖。通过正确配置 PyPI 镜像源，中国大陆的用户也能够充分享受 uv 带来的便利。

希望这篇教程能帮助你顺利在中国大陆网络环境下安装和使用 uv！

uv install python版本慢的解决办法：

设置环境变量： linux:

export UV_PYTHON_INSTALL_MIRROR="https://ghfast.top/https://github.com/astral-sh/python-build-standalone/releases/download

windows:

$env:UV_PYTHON_INSTALL_MIRROR="https://ghfast.top/https://github.com/astral-sh/python-build-standalone/releases/download"

创建指定 Python 版本的虚拟环境 (venv) 主要有两种情况：

1. 你的系统上安装了多个 Python 版本。 这种情况下，你希望虚拟环境使用其中一个特定版本的解释器。

2. 你想要一个不同于当前默认系统 Python 版本的虚拟环境。

uv venv 默认会使用当前环境中激活的 Python 解释器版本来创建虚拟环境。如果你的 PATH 环境变量中有多个 Python 解释器，或者你希望指定一个不在 PATH 中的解释器，你需要明确告诉 uv 使用哪个。

下面是几种常见的方法来创建指定 Python 版本的虚拟环境：

方法一：通过指定 Python 可执行文件路径 (最推荐且通用)

这是最直接也最可靠的方法。uv venv 允许你通过 --python (或 -p) 选项指定用于创建虚拟环境的 Python 解释器的路径。

1. 查找你想要使用的 Python 解释器路径。

   • Linux/macOS: 你可以通过 which python3.9 或 which python3.10 等命令来查找不同版本的 Python 解释器路径。例如，你可能在 /usr/bin/python3.9 或 /usr/local/bin/python3.10 找到它们。

   • Windows: 你可能在 C:\Python39\python.exe 或 C:\Users\YourUser\AppData\Local\Programs\Python\Python310\python.exe 找到它们。

2. 使用 uv venv --python <path_to_python_executable> 创建虚拟环境。

   假设你想创建一个基于 Python 3.9 的虚拟环境：

   • Linux/macOS 示例：

     
     
     
     
     
     
     uv venv --python /usr/bin/python3.9 my_project_py39_env
     

     或者，如果你知道 python3.9 在你的 PATH 中：

     
     
     
     
     
     
     uv venv --python python3.9 my_project_py39_env
     

   • Windows 示例：

     
     
     
     
     
     
     uv venv --python "C:\Python39\python.exe" my_project_py39_env
     

     或者，如果你知道 python3.9 在你的 PATH 中：

     
     
     
     
     
     
     uv venv --python python3.9 my_project_py39_env
     

   这会在当前目录下创建一个名为 my_project_py39_env 的虚拟环境，并使用指定的 Python 3.9 解释器。

方法二：通过激活特定 Python 版本的环境再创建

如果你使用 pyenv、conda 或其他类似的工具来管理多个 Python 版本，你可以先激活你想要使用的 Python 版本，然后再使用 uv venv。

1. 使用你的 Python 版本管理工具激活目标 Python 版本。

   • 使用 pyenv：

     
     
     
     
     
     
     pyenv local 3.9.18 # 或者 pyenv shell 3.9.18
     
     python --version # 确认当前 Python 版本是 3.9.18
     

   • 使用 conda：

     
     
     
     
     
     
     conda activate my_py39_env # 激活一个已经创建的 conda 虚拟环境
     
     python --version # 确认当前 Python 版本
     

2. 在激活的环境中运行 uv venv：

   
   
   
   
   
   
   uv venv my_project_env
   

   此时 uv 将使用当前激活环境中的 Python 解释器来创建新的虚拟环境。

方法三：通过调整 PATH 环境变量 (临时或永久)

你也可以通过临时或永久调整你的 shell 的 PATH 环境变量，让 uv 优先找到你希望使用的 Python 版本。

临时调整 PATH (当前 shell 会话有效)

在当前终端会话中，将你想要使用的 Python 解释器目录添加到 PATH 的开头：

• Linux/macOS:

  
  
  
  
  
  
  export PATH="/usr/bin/python3.9:$PATH" # 将 Python 3.9 的目录放到最前面
  
  python --version # 确认当前 Python 版本
  uv venv my_project_env
  

• Windows (PowerShell):

  
  
  
  
  
  
  $env:Path = "C:\Python39;$env:Path" # 将 Python 3.9 的目录放到最前面
  
  python --version # 确认当前 Python 版本
  uv venv my_project_env
  

永久调整 PATH

通常不建议为了创建虚拟环境而永久修改系统 PATH。如果你确实需要，请参考你的操作系统文档。

示例图示

假设你的系统上安装了 Python 3.9 和 Python 3.10。

如果你直接运行 uv venv，它可能会使用你的默认 Python 版本（比如 Python 3.10）。

# 假设默认是 Python 3.10

python --version
# Python 3.10.x
uv venv my_default_env
# 创建的虚拟环境将基于 Python 3.10

如果你想指定使用 Python 3.9，你需要明确指出：

uv venv --python /usr/bin/python3.9 my_py39_env

# 或者在 Windows 上
uv venv --python "C:\Python39\python.exe" my_py39_env

这将创建一个使用 Python 3.9 的虚拟环境。

(想象一下这张图片：左边是一个命令行窗口，显示 python --version 输出 Python 3.10.x，然后 uv venv my_default_env 命令。右边是另一个命令行窗口，显示 uv venv --python /usr/bin/python3.9 my_py39_env，并配有一个图标指示虚拟环境的 Python 版本。)

总结

对于 uv，最推荐和最通用的方法是使用 --python (或 -p) 选项直接指定 Python 解释器的完整路径或其在 PATH 中的可执行名称。这提供了最大的灵活性和明确性，确保你创建的虚拟环境是基于你想要的特定 Python 版本。

相关文档：uv 中文文档