Computer Science

WangMC Blog

miniconda中pip和uv换源

发表于 分类于
本文字数： 3.9k 阅读时长 ≈ 4 分钟

以下是在Miniconda环境中为pip和uv（Python包管理器）更换国内镜像源的完整指南，涵盖临时换源（单次生效）、永久换源（全局生效）及验证方法，适配不同操作系统。

前置说明

  • 环境隔离性：Miniconda的虚拟环境相互独立，pip和uv的换源配置对当前激活的环境生效（若需在其他环境使用，需重新配置或确保配置为用户级全局生效）。

  • 国内源选择：优先推荐稳定源（清华、阿里云、腾讯云），避免使用长期未更新的源（如豆瓣源）。

一、pip换源（适用于pip install命令）

1. 常用国内镜像源

镜像源 源地址（index-url）
清华源 https://pypi.tuna.tsinghua.edu.cn/simple
阿里云 https://mirrors.aliyun.com/pypi/simple/
腾讯云 https://mirrors.cloud.tencent.com/pypi/simple/
中科大源 https://pypi.mirrors.ustc.edu.cn/simple/

2. 临时换源（单次安装时使用）

通过-i参数指定源，仅对当前pip install命令生效，无需修改配置：

1
2
3
4
5
# 激活目标Miniconda环境（如pyside6_env）
conda activate pyside6_env

# 示例：用清华源安装pyside6
pip install pyside6 -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 永久换源（全局默认生效）

通过配置文件指定默认源，一劳永逸。不同操作系统的配置文件路径不同，需手动创建/修改。

（1）Windows系统

  • 配置文件路径：C:\Users\你的用户名\AppData\Roaming\pip\pip.ini
    （AppData为隐藏文件夹，需开启“显示隐藏文件”）

  • 创建/修改步骤：

    1. 进入路径后，若不存在pip文件夹，手动新建；
    2. 在pip文件夹内新建pip.ini文件（无.txt后缀）；
    3. 写入以下内容（以清华源为例）：
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      [global]
      # 1. 主源：优先从清华源下载
      index-url = https://pypi.tuna.tsinghua.edu.cn/simple
      # 2. 额外源：主源找不到时，依次从阿里云、豆瓣源查找（可添加任意数量）
      extra-index-url = 
          https://mirrors.aliyun.com/pypi/simple/
          https://pypi.doubanio.com/simple/
      # 3. 信任所有源（避免 SSL 验证错误，每个源都要加）
      trusted-host = 
          pypi.tuna.tsinghua.edu.cn
          mirrors.aliyun.com
          pypi.doubanio.com

      [install]
      # 可选：安装时禁止缓存（避免旧包干扰，按需开启）
      no-cache-dir = false

（2）Linux/macOS系统

  • 配置文件路径：~/.pip/pip.conf（~为用户主目录，如/home/用户名）

  • 创建/修改步骤：

    1. 终端执行命令创建目录和文件：
      1
      mkdir -p ~/.pip && touch ~/.pip/pip.conf
    2. 用编辑器（如vim）打开文件：
      1
      vim ~/.pip/pip.conf
    3. 写入以下内容（以阿里云为例）：
      1
      2
      3
      4
      [global]
      index-url = https://mirrors.aliyun.com/pypi/simple/
      [install]
      trusted-host = mirrors.aliyun.com
    4. 保存退出（vim中按ESC后输入:wq）。

4. 验证换源结果

执行以下命令查看当前pip配置，确认index-url为目标源：

1
pip config list

输出类似global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'即成功。

二、uv换源（适用于uv install命令，uv是快速包管理器）

1. 前置：在Miniconda环境中安装uv

为确保UV可全局调用并适配Miniconda的环境机制，建议在Miniconda的基础环境（base）中安装UV：

  1. 激活base环境：安装完成后默认激活，若已退出可执行以下命令：

    ​ Windows：conda activate base

    ​ Linux/macOS：source ~/miniconda3/bin/activate（路径需与安装时一致）

  2. 安装UV：根据系统执行对应命令：

    ​ Linux/macOS：curl -LsSf https://astral.sh/uv/install.sh | sh

    ​ Windows（PowerShell）：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  3. 验证安装：执行uv --version，输出类似"uv 0.1.30"即表示安装成功。

2. 常用国内镜像源（同pip，uv兼容PyPI格式源）

镜像源 源地址（index-url）
清华源 https://pypi.tuna.tsinghua.edu.cn/simple
阿里云 https://mirrors.aliyun.com/pypi/simple/

3. 临时换源（单次安装时使用）

通过--index-url（简写-i）参数指定源，仅对当前uv install命令生效：

1
2
# 示例：用清华源安装pyside6
uv install pyside6 --index-url https://pypi.tuna.tsinghua.edu.cn/simple

4. 永久换源（全局默认生效）

推荐用uv自带的config命令配置，或手动修改配置文件。

（1）通过uv config命令配置（推荐）

在激活的环境中执行以下命令（以清华源为例）：

1
2
3
4
5
# 设置默认索引源
uv config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple https://mirrors.aliyun.com/pypi/simple/ https://pypi.doubanio.com/simple/

# （可选）信任源主机，避免证书验证问题
uv config set global.trusted-host pypi.tuna.tsinghua.edu.cn mirrors.aliyun.com pypi.doubanio.com

（2）手动修改配置文件（适用于命令失效时）

不同操作系统的uv配置文件路径：

操作系统 配置文件路径
Windows %APPDATA%\uv\config.toml（如C:\Users\用户名\AppData\Roaming\uv\uv.toml）
Linux ~/.config/uv/config.toml
macOS ~/.config/uv/config.toml

  • 操作步骤：

    1. 按路径创建uv文件夹和uv.toml文件（若不存在）；
    2. 写入以下内容（以阿里云为例）：
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      # uv.toml - 用户级全局配置示例 (Windows: %APPDATA%\uv\uv.toml)

      # 1. 阿里云作为主源 (default = true)
      # uv 默认会从第一个 default = true 的源开始搜索
      [[index]]
      url = "https://mirrors.aliyun.com/pypi/simple/"
      default = true
      trust-host = true # 信任此主机，等同于 pip 的 trusted-host

      # 2. 清华镜像作为额外源
      [[index]]
      url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
      trust-host = true

      # 3. 豆瓣镜像作为额外源
      [[index]]
      url = "https://pypi.doubanio.com/simple/"
      trust-host = true

      # 4. 中科大镜像作为额外源
      [[index]]
      url = "https://pypi.mirrors.ustc.edu.cn/simple/"
      trust-host = true

5. 验证换源结果

执行以下命令查看uv配置，确认index-url为目标源：

1
uv config list

输出类似global.index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"即成功。

三、注意事项

  1. 环境隔离：pip和uv的换源配置默认是用户级全局生效（对所有Miniconda环境有效），若需为单个环境单独配置，需在该环境中重新执行配置命令。

  2. 源的稳定性：优先选择清华、阿里云（更新及时，稳定性高），避免频繁切换源。

  3. 恢复默认源：

    • pip：删除pip.ini/pip.conf文件，或执行pip config unset global.index-url。
    • uv：执行uv config unset global.index-url和uv config unset global.trusted-host。

通过以上步骤，可在Miniconda环境中高效配置pip和uv的国内源，显著提升包下载速度。