Proxies for PyPI: How to Install Python Packages in Blocked Regions via pip

```html

PyPI — the main repository for Python packages — is periodically blocked in several countries and corporate networks. If pip install hangs or returns a connection error, this is the issue. In this article, we will explore all working methods: from environment variables to mirrors and Docker containers.

Why PyPI is Unavailable: Reasons for Blocks

Before setting up a proxy, it is important to understand what kind of block you are facing. This will determine the choice of solution.

Regional Blocks

In several countries (Iran, China, some regions of Russia during periods of sanctions), access to pypi.org and files.pythonhosted.org is blocked at the provider or government firewall level. The command pip install requests simply hangs or returns a ConnectionError.

Corporate Proxies and Firewalls

Many companies route all outgoing traffic through a corporate proxy server. If pip is not aware of this proxy, it tries to connect directly and gets rejected. A typical error in this case is: ProxyError: HTTPSConnectionPool(host='pypi.org', port=443).

Air-Gapped Servers

Production servers, servers in banks, government structures, or in isolated cloud VPCs often do not have direct access to the internet at all. Here, either an internal network proxy or a local PyPI mirror is needed.

Temporary Failures and Rate-Limiting

Sometimes PyPI itself limits the number of requests from a single IP — especially if you are deploying dozens of Docker containers simultaneously. In this case, a proxy with IP rotation solves the problem.

How to Check if PyPI is Blocked?

Run in the terminal: curl -v https://pypi.org/simple/. If the connection hangs or returns an SSL/timeout error — PyPI is unavailable from your IP. If the error contains the phrase 407 Proxy Authentication Required — you are behind a corporate proxy.

Environment Variables: The Fastest Way

The simplest and most universal way is to set the standard environment variables HTTP_PROXY and HTTPS_PROXY. Pip, like most Python libraries (requests, urllib3), automatically picks them up without additional configuration.

Linux and macOS

# Without authentication
export HTTP_PROXY="http://1.2.3.4:8080"
export HTTPS_PROXY="http://1.2.3.4:8080"

# With username and password
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"

# SOCKS5 proxy
export HTTP_PROXY="socks5://user:[email protected]:1080"
export HTTPS_PROXY="socks5://user:[email protected]:1080"

# Now install the package
pip install requests

To avoid entering commands every time, add the lines to ~/.bashrc or ~/.zshrc.

Windows (PowerShell)

# Temporarily (only for the current session)
$env:HTTP_PROXY = "http://user:[email protected]:8080"
$env:HTTPS_PROXY = "http://user:[email protected]:8080"

# Permanently (for all sessions)
[System.Environment]::SetEnvironmentVariable("HTTP_PROXY", "http://user:[email protected]:8080", "User")
[System.Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://user:[email protected]:8080", "User")

Windows (cmd)

set HTTP_PROXY=http://user:[email protected]:8080
set HTTPS_PROXY=http://user:[email protected]:8080
pip install numpy

Note: if your password contains special characters (@, #, %), you need to URL-encode them. For example, @ becomes %40.

--proxy Flag Directly in pip

If you need to use a proxy for just one command without changing global settings:

pip install pandas --proxy http://user:[email protected]:8080

# For SOCKS5, you need the pysocks package
pip install pysocks
pip install scikit-learn --proxy socks5://user:[email protected]:1080

Configuring Proxy via pip.conf and pip.ini

If you want the proxy to be used automatically every time you run pip — without manually exporting variables — write it in the pip configuration file.

Location of Configuration Files

Contents of the pip.conf File

[global]
proxy = http://user:[email protected]:8080

# If you need to ignore SSL verification (not recommended in production)
# trusted-host = pypi.org
#                files.pythonhosted.org

After saving the file, all subsequent calls to pip install will automatically use the specified proxy. You can check the current configuration with the command:

pip config list
pip config debug  # shows all configuration files and their priorities

Which Type of Proxy to Choose for PyPI

Not all proxies are equally suitable for working with PyPI. The choice depends on the reason for the block and your infrastructure.

For most developers facing PyPI blocks due to regional restrictions, datacenter proxies will be the optimal choice — they provide high download speeds for packages and stable connections. Speed is especially important when installing heavy packages like PyTorch or TensorFlow (several gigabytes).

However, if datacenter IPs are also blocked in your region (which can happen under strict government restrictions), consider residential proxies — they use IPs of real home users and are significantly less likely to be blocked.

HTTP vs HTTPS vs SOCKS5: What Does pip Support?

Pip natively supports HTTP and HTTPS proxies. For SOCKS5, an additional package needs to be installed:

# To support SOCKS5 in pip, pysocks is needed
# But there is a problem: pip is needed to install pysocks, and pip does not work without a proxy
# Solution: first install via HTTP proxy, then switch to SOCKS5

pip install pysocks --proxy http://1.2.3.4:8080
# After that, you can use SOCKS5
pip install requests --proxy socks5://user:[email protected]:1080

PyPI Mirrors as an Alternative to Proxies

If setting up a proxy seems complicated or you do not have a reliable proxy server, you can use official and unofficial PyPI mirrors. This is especially relevant for developers in China, where there are several fast local mirrors.

Popular PyPI Mirrors

How to Use a Mirror

# Once, via the -i flag
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

# Permanently, via pip.conf
# [global]
# index-url = https://pypi.tuna.tsinghua.edu.cn/simple
# trusted-host = pypi.tuna.tsinghua.edu.cn

# Multiple sources (fallback)
pip install pandas \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --extra-index-url https://pypi.org/simple/

Proxy for pip in Docker and CI/CD

When building Docker images, pip runs inside a container that may not have access to PyPI. This is a particularly common issue in corporate CI/CD pipelines (GitLab CI, GitHub Actions, Jenkins).

Passing Proxy via ARG in Dockerfile

FROM python:3.11-slim

# Declare ARG for proxy
ARG HTTP_PROXY
ARG HTTPS_PROXY

# Pass to ENV for pip and other tools
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Reset proxy after installation (security)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

COPY . .
CMD ["python", "app.py"]

Build with proxy passing:

docker build \
  --build-arg HTTP_PROXY=http://user:[email protected]:8080 \
  --build-arg HTTPS_PROXY=http://user:[email protected]:8080 \
  -t myapp .

Global Proxy Settings for Docker Daemon

# File: ~/.docker/config.json
{
  "proxies": {
    "default": {
      "httpProxy": "http://user:[email protected]:8080",
      "httpsProxy": "http://user:[email protected]:8080",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

GitLab CI / GitHub Actions

# .gitlab-ci.yml
variables:
  HTTP_PROXY: "http://user:[email protected]:8080"
  HTTPS_PROXY: "http://user:[email protected]:8080"
  PIP_INDEX_URL: "https://pypi.tuna.tsinghua.edu.cn/simple"

install:
  script:
    - pip install -r requirements.txt

# .github/workflows/ci.yml
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: ${{ secrets.HTTP_PROXY }}
      HTTPS_PROXY: ${{ secrets.HTTP_PROXY }}
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: pip install -r requirements.txt

Important: never hardcode proxy credentials directly in YAML files. Use secrets from your CI/CD service.

Configuring Proxy for Poetry, conda, and uv

Modern Python projects increasingly use alternative package managers. Let's look at configuring proxies for each of them.

Poetry

Poetry uses environment variables just like pip. But there is a nuance — Poetry uses its own HTTP client based on requests, so the standard variables work:

# Works for Poetry
export HTTPS_PROXY=http://user:[email protected]:8080
poetry install

# Or configure the source in pyproject.toml
# [[tool.poetry.source]]
# name = "tsinghua"
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# priority = "primary"

conda / mamba

conda has its own configuration system:

# Via command
conda config --set proxy_servers.http http://user:[email protected]:8080
conda config --set proxy_servers.https http://user:[email protected]:8080

# Or directly in ~/.condarc
# proxy_servers:
#   http: http://user:[email protected]:8080
#   https: http://user:[email protected]:8080

# Conda mirror for China
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --set show_channel_urls yes

uv (new fast package manager)

uv from Astral is one of the fastest package managers for Python. It also supports standard environment variables:

export HTTPS_PROXY=http://user:[email protected]:8080
uv pip install numpy

# Or with the index flag
uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

pipenv

# pipenv inherits environment variables from pip
export HTTPS_PROXY=http://user:[email protected]:8080
pipenv install requests

# Change source in Pipfile
# [[source]]
# url = "https://pypi.tuna.tsinghua.edu.cn/simple"
# verify_ssl = true
# name = "tsinghua"

Common Errors and How to Fix Them

Let's discuss the most common issues developers face when configuring proxies for pip.

Error 1: SSL Certificate Verification Failed

# Error:
# SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate

# Reason: corporate proxy replaces SSL certificates (MITM)
# Solution 1: add corporate CA certificate
pip install requests --cert /path/to/corporate-ca.crt

# Solution 2: specify the path to the certificate in pip.conf
# [global]
# cert = /path/to/corporate-ca.crt

# Solution 3 (NOT recommended for production): disable SSL verification
pip install requests --trusted-host pypi.org --trusted-host files.pythonhosted.org

Error 2: 407 Proxy Authentication Required

# Error:
# ProxyError: 407 Proxy Authentication Required

# Reason: the proxy requires authentication, but the username/password were not provided
# Solution: ensure that credentials are correctly encoded

# If the password contains special characters, encode them:
python3 -c "from urllib.parse import quote; print(quote('my@pass#word'))"
# Output: my%40pass%23word

export HTTPS_PROXY="http://user:my%40pass%[email protected]:8080"

Error 3: pip Ignores Environment Variables

# Check that the variables are set correctly
echo $HTTPS_PROXY  # Linux/macOS
echo %HTTPS_PROXY%  # Windows cmd

# Check pip configuration priority
pip config debug

# Possible reason: the virtual environment does not see system variables
# Solution: activate venv and set the variables again
source venv/bin/activate
export HTTPS_PROXY=http://1.2.3.4:8080
pip install package-name

Error 4: Connection Timeout Even Through Proxy

# Check proxy availability
curl -v --proxy http://user:[email protected]:8080 https://pypi.org/simple/

# If the proxy is unavailable — the problem lies with the proxy server itself
# Try another port or protocol

# Increase pip timeout
pip install package-name --timeout 120

# Or in pip.conf:
# [global]
# timeout = 120

Error 5: Package Installed, But Import Does Not Work

This is not related to the proxy — most likely, the package was installed in the system Python, not in the active virtual environment. Check:

which pip      # should point to pip inside venv
which python   # should point to python inside venv
pip show requests  # will show where the package was installed

Proxy Debugging Checklist for pip

Conclusion

Blocking PyPI is a solvable problem, and there are several reliable solutions. For a quick start, simply set the HTTPS_PROXY variable and run pip as usual. For continuous operation — specify the proxy in pip.conf. For CI/CD — use secrets and ARG in Docker.

The choice between a proxy and a mirror depends on the context: mirrors are faster and easier to set up, but require trust in the mirror operator. Proxies are more versatile — they work not only with PyPI but also with any other blocked resources (npm, Docker Hub, GitHub).

If you need a reliable proxy for working with PyPI, GitHub, Docker Hub, and other blocked resources in your region, consider datacenter proxies — they provide high speeds when downloading heavy packages and work reliably in CI/CD environments. If your region blocks even datacenter IPs, consider residential proxies with IPs of real home users — they are significantly less likely to fall under regional blocks.