Proxies para PyPI: como instalar pacotes Python em regiões bloqueadas via pip

```html

PyPI — o principal repositório de pacotes Python — é periodicamente bloqueado em vários países e redes corporativas. Se pip install está travando ou retornando um erro de conexão, o problema é exatamente esse. Neste artigo, vamos explorar todas as maneiras funcionais: desde variáveis de ambiente até espelhos e contêineres Docker.

Por que o PyPI está indisponível: razões para bloqueios

Antes de configurar um proxy, é importante entender qual bloqueio você está enfrentando. Isso afetará a escolha da solução.

Bloqueios regionais

Em vários países (Irã, China, algumas regiões da Rússia durante períodos de sanções), o acesso ao pypi.org e files.pythonhosted.org é bloqueado no nível do provedor ou do firewall governamental. O comando pip install requests simplesmente trava ou retorna um ConnectionError.

Proxies corporativos e firewalls

Muitas empresas direcionam todo o tráfego de saída através de um servidor proxy corporativo. Se o pip não souber sobre esse proxy, ele tentará se conectar diretamente e receberá uma recusa. Um erro típico nesse caso é: ProxyError: HTTPSConnectionPool(host='pypi.org', port=443).

Servidores sem acesso à internet (air-gapped)

Servidores de produção, servidores em bancos, estruturas governamentais ou em VPCs isoladas geralmente não têm acesso direto à internet. Aqui, é necessário um servidor proxy dentro da rede ou um espelho local do PyPI.

Interrupções temporárias e rate-limiting

Às vezes, o PyPI limita o número de solicitações de um único IP — especialmente se você estiver implantando dezenas de contêineres Docker ao mesmo tempo. Nesse caso, um proxy com rotação de IP resolve o problema.

Como verificar se o PyPI está bloqueado?

Execute no terminal: curl -v https://pypi.org/simple/. Se a conexão travar ou retornar um erro SSL/timeout — o PyPI está indisponível do seu IP. Se o erro contiver a palavra 407 Proxy Authentication Required — você está atrás de um proxy corporativo.

Variáveis de ambiente: a maneira mais rápida

A maneira mais simples e universal é definir as variáveis de ambiente padrão HTTP_PROXY e HTTPS_PROXY. O pip, assim como a maioria das bibliotecas Python (requests, urllib3), as captura automaticamente sem configuração adicional.

Linux e macOS

# Sem autenticação
export HTTP_PROXY="http://1.2.3.4:8080"
export HTTPS_PROXY="http://1.2.3.4:8080"

# Com login e senha
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"

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

# Agora instalamos o pacote
pip install requests

Para não precisar digitar os comandos toda vez, adicione as linhas em ~/.bashrc ou ~/.zshrc.

Windows (PowerShell)

# Temporariamente (apenas para a sessão atual)
$env:HTTP_PROXY = "http://user:[email protected]:8080"
$env:HTTPS_PROXY = "http://user:[email protected]:8080"

# Permanentemente (para todas as sessões)
[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

Observe: se a senha contiver caracteres especiais (@, #, %), eles precisam ser URL-encoded. Por exemplo, @ se torna %40.

Flag --proxy diretamente no pip

Se precisar usar o proxy apenas para um comando, sem alterar as configurações globais:

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

# Para SOCKS5 é necessário o pacote pysocks
pip install pysocks
pip install scikit-learn --proxy socks5://user:[email protected]:1080

Configuração do proxy através de pip.conf e pip.ini

Se você quiser que o proxy seja usado automaticamente a cada execução do pip — sem a necessidade de exportar variáveis manualmente — escreva-o no arquivo de configuração do pip.

Localização dos arquivos de configuração

Conteúdo do arquivo pip.conf

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

# Se precisar ignorar a verificação SSL (não recomendado em produção)
# trusted-host = pypi.org
#                files.pythonhosted.org

Após salvar o arquivo, todas as chamadas subsequentes de pip install usarão automaticamente o proxy especificado. Você pode verificar a configuração atual com o comando:

pip config list
pip config debug  # mostra todos os arquivos de configuração e suas prioridades

Qual tipo de proxy escolher para o PyPI

Nem todos os proxies são igualmente adequados para trabalhar com o PyPI. A escolha depende da razão do bloqueio e da sua infraestrutura.

Para a maioria dos desenvolvedores que enfrentam bloqueios do PyPI devido a restrições regionais, a escolha ideal será proxies de datacenter — eles oferecem alta velocidade de download de pacotes e uma conexão estável. A velocidade é especialmente importante quando é necessário instalar pacotes pesados como PyTorch ou TensorFlow (vários gigabytes).

Se os IPs de datacenter também estão bloqueados na sua região (isso acontece em restrições governamentais severas), considere usar proxies residenciais — eles utilizam IPs de usuários reais e são significativamente menos propensos a bloqueios.

HTTP vs HTTPS vs SOCKS5: o que o pip suporta?

O pip suporta proxies HTTP e HTTPS nativamente. Para SOCKS5, é necessário instalar um pacote adicional:

# Para suporte a SOCKS5 no pip, é necessário o pysocks
# Mas há um problema: o pip precisa ser usado para instalar o pysocks, e o pip não funciona sem proxy
# Solução: primeiro instale através do proxy HTTP, depois mude para SOCKS5

pip install pysocks --proxy http://1.2.3.4:8080
# Depois disso, você pode usar SOCKS5
pip install requests --proxy socks5://user:[email protected]:1080

Espelhos do PyPI como alternativa ao proxy

Se configurar um proxy parece complicado ou você não tem um servidor proxy confiável, pode usar espelhos oficiais e não oficiais do PyPI. Isso é especialmente relevante para desenvolvedores na China, onde existem vários espelhos locais rápidos.

Espelhos populares do PyPI

Como usar um espelho

# Uma vez, através da flag -i
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

# Permanentemente, através do pip.conf
# [global]
# index-url = https://pypi.tuna.tsinghua.edu.cn/simple
# trusted-host = pypi.tuna.tsinghua.edu.cn

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

Proxy para pip no Docker e CI/CD

Ao construir imagens Docker, o pip é executado dentro de um contêiner que pode não ter acesso ao PyPI. Este é um problema especialmente comum em pipelines corporativos de CI/CD (GitLab CI, GitHub Actions, Jenkins).

Passando o proxy através de ARG no Dockerfile

FROM python:3.11-slim

# Declaramos ARG para o proxy
ARG HTTP_PROXY
ARG HTTPS_PROXY

# Passamos para ENV para pip e outras ferramentas
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

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

# Resetamos o proxy após a instalação (segurança)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

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

Construção passando o proxy:

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

Configuração global do proxy para o daemon Docker

# Arquivo: ~/.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

Importante: nunca codifique as credenciais do proxy diretamente nos arquivos YAML. Use os segredos (Secrets) do seu serviço de CI/CD.

Configuração do proxy para Poetry, conda e uv

Projetos modernos em Python estão cada vez mais utilizando gerenciadores de pacotes alternativos. Vamos considerar a configuração do proxy para cada um deles.

Poetry

O Poetry utiliza variáveis de ambiente da mesma forma que o pip. Mas há uma nuance — o Poetry utiliza seu próprio cliente HTTP baseado em requests, portanto, as variáveis padrão funcionam:

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

# Ou configuração da fonte em pyproject.toml
# [[tool.poetry.source]]
# name = "tsinghua"
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# priority = "primary"

conda / mamba

O conda possui seu próprio sistema de configuração:

# Através do comando
conda config --set proxy_servers.http http://user:[email protected]:8080
conda config --set proxy_servers.https http://user:[email protected]:8080

# Ou diretamente em ~/.condarc
# proxy_servers:
#   http: http://user:[email protected]:8080
#   https: http://user:[email protected]:8080

# Espelho conda para a China
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --set show_channel_urls yes

uv (novo gerenciador de pacotes rápido)

uv da Astral — é um dos gerenciadores de pacotes mais rápidos para Python. Ele também suporta as variáveis de ambiente padrão:

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

# Ou com a flag index
uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

pipenv

# pipenv herda variáveis de ambiente do pip
export HTTPS_PROXY=http://user:[email protected]:8080
pipenv install requests

# Mudança da fonte no Pipfile
# [[source]]
# url = "https://pypi.tuna.tsinghua.edu.cn/simple"
# verify_ssl = true
# name = "tsinghua"

Erros comuns e como resolvê-los

Vamos analisar os problemas mais comuns que os desenvolvedores enfrentam ao configurar um proxy para o pip.

Erro 1: SSL Certificate Verification Failed

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

# Causa: o proxy corporativo substitui os certificados SSL (MITM)
# Solução 1: adicione o certificado CA corporativo
pip install requests --cert /path/to/corporate-ca.crt

# Solução 2: especifique o caminho para o certificado em pip.conf
# [global]
# cert = /path/to/corporate-ca.crt

# Solução 3 (NÃO recomendado para produção): desabilitar a verificação SSL
pip install requests --trusted-host pypi.org --trusted-host files.pythonhosted.org

Erro 2: 407 Proxy Authentication Required

# Erro:
# ProxyError: 407 Proxy Authentication Required

# Causa: o proxy requer autenticação, mas o login/senha não foram fornecidos
# Solução: certifique-se de que as credenciais estão codificadas corretamente

# Se a senha contiver caracteres especiais, codifique-os:
python3 -c "from urllib.parse import quote; print(quote('my@pass#word'))"
# Saída: my%40pass%23word

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

Erro 3: pip ignora variáveis de ambiente

# Verifique se as variáveis estão definidas corretamente
echo $HTTPS_PROXY  # Linux/macOS
echo %HTTPS_PROXY%  # Windows cmd

# Verifique a prioridade da configuração do pip
pip config debug

# Possível causa: o ambiente virtual não vê as variáveis de sistema
# Solução: ative o venv e defina as variáveis novamente
source venv/bin/activate
export HTTPS_PROXY=http://1.2.3.4:8080
pip install package-name

Erro 4: Connection timeout mesmo através do proxy

# Verifique a disponibilidade do proxy
curl -v --proxy http://user:[email protected]:8080 https://pypi.org/simple/

# Se o proxy estiver indisponível — o problema está no próprio servidor proxy
# Tente outra porta ou protocolo

# Aumente o timeout do pip
pip install package-name --timeout 120

# Ou em pip.conf:
# [global]
# timeout = 120

Erro 5: Pacote instalado, mas importação não funciona

Isso não está relacionado ao proxy — provavelmente, o pacote foi instalado no Python do sistema, e não no ambiente virtual ativo. Verifique:

which pip      # deve apontar para pip dentro do venv
which python   # deve apontar para python dentro do venv
pip show requests  # mostrará onde o pacote foi instalado

Checklist de depuração do proxy para pip

Conclusão

O bloqueio do PyPI é um problema solucionável, e existem várias soluções confiáveis. Para um início rápido, basta definir a variável HTTPS_PROXY e executar o pip normalmente. Para um funcionamento contínuo — registre o proxy em pip.conf. Para CI/CD — use segredos e ARG no Docker.

A escolha entre proxy e espelho depende do contexto: espelhos são mais rápidos e fáceis de configurar, mas exigem confiança no operador do espelho. Proxies são mais versáteis — eles funcionam não apenas com o PyPI, mas também com quaisquer outros recursos bloqueados (npm, Docker Hub, GitHub).

Se você precisa de um proxy confiável para trabalhar com PyPI, GitHub, Docker Hub e outros recursos bloqueados na sua região, considere proxies de datacenter — eles oferecem alta velocidade ao baixar pacotes pesados e funcionam de forma estável em ambientes de CI/CD. Se, no entanto, os IPs de datacenter estão bloqueados na sua região, considere proxies residenciais com IPs de usuários reais — eles são significativamente menos propensos a bloqueios regionais.