If you frequently work with AI tools, especially open-source ones, you'll inevitably encounter situations where you need to deploy Python-based solutions locally. This often involves using pip, and you might run into frustrating errors, such as extremely slow download speeds (e.g., a few KB/s), making downloading multi-gigabyte models take forever.

Sometimes, downloads fail completely with errors like cannot connect to huggingface.co. Even after setting up a VPN or proxy, you might still face issues like proxyError or max retries.

Here's how to troubleshoot and resolve some of these common pip problems.

1. Slow Download Speeds

The default pip download source is located outside of China. Due to various factors, download speeds within China can be significantly slow.

Temporarily Use the Aliyun Mirror

For single module installations or occasional use, you can specify the Aliyun mirror on the command line:

pip install xx模块名 -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

Replace xx模块名 with the name of the module you want to install.

Permanently Set the Aliyun Mirror

If you use pip frequently, the temporary solution is inconvenient. To permanently configure the mirror, navigate to the pip directory in your user folder:

On Windows: C:\Users\YourUsername\pip (create the pip folder if it doesn't exist).

Inside the pip folder, create a file named pip.ini (if it doesn't exist). Ensure the file extension is .ini, not .txt.

Open pip.ini and replace its contents with:

[global]
index-url = http://mirrors.aliyun.com/pypi/simple/

[install]
trusted-host=mirrors.aliyun.com

How to Use Other Mirror Sources? (e.g., Tsinghua University)

The process is the same. The only difference is the index-url and trusted-host values, which you should replace with the values provided by the desired mirror.

# Douban:
[global]
index-url = https://pypi.douban.com/simple/

[install]
trusted-host=pypi.douban.com

# Tsinghua University:
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple/

[install]
trusted-host=pypi.tuna.tsinghua.edu.cn

# University of Science and Technology of China:
[global]
index-url = https://pypi.mirrors.ustc.edu.cn/simple/

[install]
trusted-host=pypi.mirrors.ustc.edu.cn

2. Still Getting Errors After Using a Domestic Mirror?

Check the error messages for occurrences of proxyError or Retrying (Retry(total=4. See the example below:

Domestic mirrors often block downloads from foreign IP addresses. If you encounter this, disable your proxy or VPN. Alternatively, revert to the default pip source by deleting the pip.ini file.

3. A Lot of Red Error Messages with Version Numbers

See the example below:

This error indicates that the specific version you requested doesn't exist. The versions listed after from versions: are the available options. Choose a version number that is close to your desired version and shares the same initial major version number.

For example, if you tried to install requests==2.32.0 but it's unavailable, observe the available versions. In the image, 2.32.2 is the closest available version starting with 2.. So, change the command to pip install requests==2.32.2.

Other Potential Issues: You might encounter module conflicts. For instance, modules a and b might both depend on module c, but a requires version 1.2 of c, while b requires version 3.6. This creates a conflict. The solution depends on your specific requirements and project dependencies. You may need to explore virtual environments or carefully manage your dependencies.