Captured at (local ISO): 2026-05-18 05:16:58

---

Preface

If you use Python often, you have probably seen this: you want to install a third‑party package such as requests or pandas, you run pip install requests in the terminal, and the progress bar barely moves—it either hangs on “Collecting requests” or throws ReadTimeoutError. That is not necessarily because your network is bad; pip’s default index is on overseas servers (https://pypi.org/simple/). With routing and bandwidth limits, speeds are naturally frustrating.

The fix is simple: point pip at a domestic mirror (a local server that replicates the foreign index so you download from a nearby node). This article walks you from the basics to hands‑on steps so you can configure pip mirrors with confidence.

1. What is pip?

pip is Python’s official package manager. Think of it as an “app store” for libraries: install third‑party packages (e.g. numpy for data analysis, scrapy for crawling), uninstall what you do not need, upgrade old versions, or list what is installed.

The catch: by default it talks to the global PyPI index abroad. Long paths and limited bandwidth often mean tens of KB/s in China, and larger packages (e.g. TensorFlow) may time out. That is why mirror configuration matters.

2. Mirror sites

2.1 What is a mirror site?

A mirror is a replica: companies and schools periodically sync everything from PyPI to servers in China. When you install via a mirror, files are fetched from those nearby hosts, which is usually much faster than the official PyPI host.

2.2 Mainstream mirror sites

Below are common mirrors; you can also visit their URLs to see how they are organized.

Mirror	URL
Tsinghua University	https://pypi.tuna.tsinghua.edu.cn/simple/
Alibaba Cloud	https://mirrors.aliyun.com/pypi/simple/
Douban	https://pypi.doubanio.com/simple/
University of Science and Technology of China	https://pypi.mirrors.ustc.edu.cn/simple/
Huawei Cloud	https://mirrors.huaweicloud.com/repository/pypi/simple/
Nanjing University	https://mirrors.nju.edu.cn/simple/

3. Configure a mirror

3.1 Temporary configuration

If you only need a one‑off install and do not want to change global settings, add -i to pip install to pick a mirror for that command only.

Install requests using the Tsinghua mirror:

pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple/

Install a specific NumPy version (1.24.3) using the Alibaba mirror:

pip install numpy==1.24.3 -i https://mirrors.aliyun.com/pypi/simple/

3.2 Permanent configuration

Option 1: Command line

Step 1: set the global index
pip config edits the global config directly—no need to hunt for files; works on Windows, macOS, and Linux.
Open a terminal (Command Prompt or PowerShell on Windows; Terminal on macOS/Linux) and run (Tsinghua example):

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/

Step 2: trusted host (optional, reduces warnings)
Some mirrors trigger “untrusted host” warnings. Add the host to the trust list:

pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

(The value after trusted-host is the mirror’s domain—strip https:// and /simple/.)

Step 3: verify
List current pip configuration:

pip config list

If the output includes your mirror URL, the change took effect.

Option 2: Edit the config file manually (custom scenarios)

If CLI configuration fails (e.g. permissions) or you need multiple mirrors (primary + fallback), create or edit pip’s config file manually. Paths differ by OS.

1. Windows (Win10/11)
Step 1: locate the file
Default: C:\Users\<YourUsername>\pip\pip.ini

If the pip folder or pip.ini is missing, create it:
Under C:\Users\<YourUsername>\, create folder pip;
Inside pip, create a new text file and rename it to pip.ini (extension .ini, not .txt).

Step 2: edit contents
Open pip.ini in Notepad or Notepad++ and paste (Tsinghua example):

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple/
trusted-host = pypi.tuna.tsinghua.edu.cn
# Optional: fallback index if the primary is down
# extra-index-url = https://mirrors.aliyun.com/pypi/simple/

2. macOS / Linux

Step 1: locate the file
Default: ~/.config/pip/pip.conf (~ is your home directory).
macOS: /Users/<YourUsername>/
Linux: /home/<YourUsername>/

Create if missing:

mkdir -p ~/.config/pip
touch ~/.config/pip/pip.conf

Step 2: edit contents
Open pip.conf with vim or any editor and paste (Alibaba example):

[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
trusted-host = mirrors.aliyun.com
# Optional: timeout in seconds for slow networks
timeout = 120

Step 3: verify
Run:

pip config list

If you see the settings, it worked.

---

4. Summary

Which method to use:

• Temporary -i: occasional installs; no global change.
• Permanent via CLI: fastest for beginners; no file hunting.
• Permanent via config file: advanced customization (fallback URLs, timeouts).

If a mirror slows down or goes away, switch to another from the table above.