Proxies para PyPI: cómo instalar paquetes de Python en regiones bloqueadas a través de pip

```html

PyPI — el principal repositorio de paquetes de Python — se bloquea periódicamente en varios países y redes corporativas. Si pip install se queda colgado o muestra un error de conexión, el problema es precisamente este. En este artículo analizaremos todas las formas efectivas: desde variables de entorno hasta espejos y contenedores Docker.

Por qué PyPI no está disponible: razones de los bloqueos

Antes de configurar un proxy, es importante entender qué tipo de bloqueo ha encontrado. Esto determinará la elección de la solución.

Bloqueos regionales

En varios países (Irán, China, algunas regiones de Rusia durante períodos de sanciones) el acceso a pypi.org y files.pythonhosted.org se bloquea a nivel de proveedor o firewall estatal. El comando pip install requests simplemente se queda colgado o muestra ConnectionError.

Proxies y firewalls corporativos

Muchas empresas dirigen todo el tráfico saliente a través de un servidor proxy corporativo. Si pip no conoce este proxy, intenta conectarse directamente y recibe una negativa. Un error típico en este caso es: ProxyError: HTTPSConnectionPool(host='pypi.org', port=443).

Servidores sin acceso a Internet (air-gapped)

Los servidores de producción, servidores en bancos, estructuras gubernamentales o en VPCs de nube aisladas a menudo no tienen acceso directo a Internet. Aquí se necesita un servidor proxy dentro de la red o un espejo local de PyPI.

Fallas temporales y limitación de tasa

A veces, PyPI limita la cantidad de solicitudes desde una sola IP — especialmente si está desplegando decenas de contenedores Docker al mismo tiempo. En este caso, un proxy con rotación de IP resuelve el problema.

¿Cómo verificar si PyPI está bloqueado?

Ejecute en la terminal: curl -v https://pypi.org/simple/. Si la conexión se queda colgada o muestra un error de SSL/timeout — PyPI no está disponible desde su IP. Si el error contiene la palabra 407 Proxy Authentication Required — está detrás de un proxy corporativo.

Variables de entorno: la forma más rápida

La forma más sencilla y universal es establecer las variables de entorno estándar HTTP_PROXY y HTTPS_PROXY. Pip, al igual que la mayoría de las bibliotecas de Python (requests, urllib3), las recoge automáticamente sin configuración adicional.

Linux y macOS

# Sin autenticación
export HTTP_PROXY="http://1.2.3.4:8080"
export HTTPS_PROXY="http://1.2.3.4:8080"

# Con usuario y contraseña
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"

# Ahora instalamos el paquete
pip install requests

Para no tener que introducir los comandos cada vez, agregue las líneas a ~/.bashrc o ~/.zshrc.

Windows (PowerShell)

# Temporal (solo para la sesión actual)
$env:HTTP_PROXY = "http://user:[email protected]:8080"
$env:HTTPS_PROXY = "http://user:[email protected]:8080"

# Permanente (para todas las sesiones)
[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

Tenga en cuenta: si la contraseña contiene caracteres especiales (@, #, %), deben ser codificados en URL. Por ejemplo, @ se convierte en %40.

La bandera --proxy directamente en pip

Si necesita usar un proxy solo para un comando, sin cambiar la configuración global:

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

# Para SOCKS5 se necesita el paquete pysocks
pip install pysocks
pip install scikit-learn --proxy socks5://user:[email protected]:1080

Configuración del proxy a través de pip.conf y pip.ini

Si desea que el proxy se utilice automáticamente en cada ejecución de pip — sin exportar manualmente las variables — escríbalo en el archivo de configuración de pip.

Ubicación de los archivos de configuración

Contenido del archivo pip.conf

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

# Si necesita ignorar la verificación SSL (no recomendado en producción)
# trusted-host = pypi.org
#                files.pythonhosted.org

Después de guardar el archivo, todas las llamadas posteriores a pip install utilizarán automáticamente el proxy especificado. Puede verificar la configuración actual con el comando:

pip config list
pip config debug  # muestra todos los archivos de configuración y sus prioridades

Qué tipo de proxy elegir para PyPI

No todos los proxies son igualmente adecuados para trabajar con PyPI. La elección depende de la razón del bloqueo y de su infraestructura.

Para la mayoría de los desarrolladores que enfrentan el bloqueo de PyPI debido a restricciones regionales, la opción óptima son los proxies de centros de datos — ofrecen alta velocidad de descarga de paquetes y conexión estable. La velocidad es especialmente importante cuando se necesita instalar paquetes pesados como PyTorch o TensorFlow (varios gigabytes).

Si las IP de centro de datos también están bloqueadas en su región (esto ocurre con restricciones gubernamentales estrictas), considere los proxies residenciales — utilizan IP de usuarios domésticos reales y son mucho menos propensos a ser bloqueados.

HTTP vs HTTPS vs SOCKS5: ¿qué soporta pip?

Pip soporta proxies HTTP y HTTPS de forma nativa. Para SOCKS5 se necesita instalar un paquete adicional:

# Para soporte de SOCKS5 en pip se necesita pysocks
# Pero hay un problema: pip necesita para instalar pysocks, y pip no funciona sin proxy
# Solución: primero instalar a través de un proxy HTTP, luego cambiar a SOCKS5

pip install pysocks --proxy http://1.2.3.4:8080
# Después de esto se puede usar SOCKS5
pip install requests --proxy socks5://user:[email protected]:1080

Espejos de PyPI como alternativa al proxy

Si la configuración del proxy parece complicada o no tiene un servidor proxy confiable, puede utilizar espejos oficiales y no oficiales de PyPI. Esto es especialmente relevante para los desarrolladores en China, donde hay varios espejos locales rápidos.

Espejos populares de PyPI

Cómo usar un espejo

# Una vez, a través de la bandera -i
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

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

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

Proxy para pip en Docker y CI/CD

Al construir imágenes de Docker, pip se ejecuta dentro de un contenedor que puede no tener acceso a PyPI. Este es un problema especialmente común en pipelines corporativos de CI/CD (GitLab CI, GitHub Actions, Jenkins).

Pasar el proxy a través de ARG en Dockerfile

FROM python:3.11-slim

# Declaramos ARG para el proxy
ARG HTTP_PROXY
ARG HTTPS_PROXY

# Pasamos a ENV para pip y otras herramientas
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

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

# Reiniciamos el proxy después de la instalación (seguridad)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

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

Construcción pasando el proxy:

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

Configuración global del proxy para el daemon de Docker

# Archivo: ~/.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 las credenciales del proxy directamente en los archivos YAML. Utilice los secretos (Secrets) de su servicio de CI/CD.

Configuración del proxy para Poetry, conda y uv

Los proyectos modernos de Python utilizan cada vez más gestores de paquetes alternativos. Veamos la configuración del proxy para cada uno de ellos.

Poetry

Poetry utiliza variables de entorno de la misma manera que pip. Pero hay un matiz — Poetry utiliza su propio cliente HTTP basado en requests, por lo que las variables estándar funcionan:

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

# O configuración de la fuente en pyproject.toml
# [[tool.poetry.source]]
# name = "tsinghua"
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# priority = "primary"

conda / mamba

Conda tiene su propio sistema de configuración:

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

# O directamente en ~/.condarc
# proxy_servers:
#   http: http://user:[email protected]:8080
#   https: http://user:[email protected]:8080

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

uv (nuevo gestor de paquetes rápido)

uv de Astral es uno de los gestores de paquetes más rápidos para Python. También soporta las variables de entorno estándar:

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

# O con la bandera index
uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

pipenv

# pipenv hereda las variables de entorno de pip
export HTTPS_PROXY=http://user:[email protected]:8080
pipenv install requests

# Cambio de fuente en Pipfile
# [[source]]
# url = "https://pypi.tuna.tsinghua.edu.cn/simple"
# verify_ssl = true
# name = "tsinghua"

Errores comunes y cómo solucionarlos

Analicemos los problemas más comunes que enfrentan los desarrolladores al configurar un proxy para pip.

Error 1: SSL Certificate Verification Failed

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

# Causa: el proxy corporativo reemplaza los certificados SSL (MITM)
# Solución 1: agregar el certificado CA corporativo
pip install requests --cert /path/to/corporate-ca.crt

# Solución 2: especificar la ruta al certificado en pip.conf
# [global]
# cert = /path/to/corporate-ca.crt

# Solución 3 (NO recomendado para producción): deshabilitar la verificación SSL
pip install requests --trusted-host pypi.org --trusted-host files.pythonhosted.org

Error 2: 407 Proxy Authentication Required

# Error:
# ProxyError: 407 Proxy Authentication Required

# Causa: el proxy requiere autenticación, pero no se han proporcionado usuario/contraseña
# Solución: asegúrese de que las credenciales estén correctamente codificadas

# Si la contraseña contiene caracteres especiales, codifíquelos:
python3 -c "from urllib.parse import quote; print(quote('my@pass#word'))"
# Salida: my%40pass%23word

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

Error 3: pip ignora las variables de entorno

# Verifique que las variables estén configuradas correctamente
echo $HTTPS_PROXY  # Linux/macOS
echo %HTTPS_PROXY%  # Windows cmd

# Verifique la prioridad de la configuración de pip
pip config debug

# Posible causa: el entorno virtual no ve las variables del sistema
# Solución: active el venv y establezca las variables nuevamente
source venv/bin/activate
export HTTPS_PROXY=http://1.2.3.4:8080
pip install package-name

Error 4: Connection timeout incluso a través del proxy

# Verifique la disponibilidad del proxy
curl -v --proxy http://user:[email protected]:8080 https://pypi.org/simple/

# Si el proxy no está disponible — el problema está en el servidor proxy mismo
# Pruebe otro puerto o protocolo

# Aumente el tiempo de espera de pip
pip install package-name --timeout 120

# O en pip.conf:
# [global]
# timeout = 120

Error 5: El paquete está instalado, pero la importación no funciona

Esto no está relacionado con el proxy — lo más probable es que el paquete se haya instalado en el Python del sistema, y no en el entorno virtual activo. Verifique:

which pip      # debe apuntar a pip dentro del venv
which python   # debe apuntar a python dentro del venv
pip show requests  # mostrará dónde se instaló el paquete

Lista de verificación para depurar el proxy para pip

Conclusión

El bloqueo de PyPI es un problema solucionable, y hay varias soluciones confiables. Para un inicio rápido, es suficiente establecer la variable HTTPS_PROXY y ejecutar pip como de costumbre. Para un funcionamiento continuo — escribir el proxy en pip.conf. Para CI/CD — usar secretos y ARG en Docker.

La elección entre un proxy y un espejo depende del contexto: los espejos son más rápidos y fáciles de configurar, pero requieren confianza en el operador del espejo. El proxy es más versátil — funciona no solo con PyPI, sino también con cualquier otro recurso bloqueado (npm, Docker Hub, GitHub).

Si necesita un proxy confiable para trabajar con PyPI, GitHub, Docker Hub y otros recursos bloqueados en su región, considere los proxies de centros de datos — ofrecen alta velocidad al descargar paquetes pesados y funcionan de manera estable en entornos de CI/CD. Si en su región también se bloquean las IP de los centros de datos, considere los proxies residenciales con IP de usuarios domésticos reales — son significativamente menos propensos a ser bloqueados por restricciones regionales.