Proxy per PyPI: come installare pacchetti Python in regioni bloccate tramite pip

```html

PyPI — il principale repository di pacchetti Python — viene periodicamente bloccato in vari paesi e reti aziendali. Se pip install si blocca o restituisce un errore di connessione, il problema è proprio questo. In questo articolo esamineremo tutti i metodi funzionanti: dalle variabili d'ambiente ai mirror e ai contenitori Docker.

Perché PyPI non è disponibile: motivi dei blocchi

Prima di configurare un proxy, è importante capire quale tipo di blocco hai incontrato. Da questo dipende la scelta della soluzione.

Blocchi regionali

In alcuni paesi (Iran, Cina, alcune regioni della Russia in periodi di sanzioni) l'accesso a pypi.org e files.pythonhosted.org è bloccato a livello di provider o firewall statale. Il comando pip install requests si blocca semplicemente o restituisce ConnectionError.

Proxy aziendali e firewall

Molte aziende instradano tutto il traffico in uscita attraverso un server proxy aziendale. Se pip non è a conoscenza di questo proxy, tenta di connettersi direttamente e riceve un rifiuto. Un errore tipico in questo caso è: ProxyError: HTTPSConnectionPool(host='pypi.org', port=443).

Server senza accesso a Internet (air-gapped)

I server di produzione, i server in banche, enti governativi o in VPC cloud isolati spesso non hanno affatto accesso diretto a Internet. Qui è necessario un server proxy all'interno della rete o un mirror locale di PyPI.

Interruzioni temporanee e rate-limiting

A volte PyPI limita il numero di richieste da un singolo IP — soprattutto se stai eseguendo decine di contenitori Docker contemporaneamente. In questo caso, un proxy con rotazione IP risolve il problema.

Come verificare se PyPI è bloccato?

Esegui nel terminale: curl -v https://pypi.org/simple/. Se la connessione si blocca o restituisce un errore SSL/timeout — PyPI non è disponibile dal tuo IP. Se l'errore contiene la parola 407 Proxy Authentication Required — sei dietro un proxy aziendale.

Variabili d'ambiente: il modo più veloce

Il modo più semplice e universale è impostare le variabili d'ambiente standard HTTP_PROXY e HTTPS_PROXY. Pip, come la maggior parte delle librerie Python (requests, urllib3), le rileva automaticamente senza configurazioni aggiuntive.

Linux e macOS

# Senza autenticazione
export HTTP_PROXY="http://1.2.3.4:8080"
export HTTPS_PROXY="http://1.2.3.4:8080"

# Con login e password
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"

# Ora installiamo il pacchetto
pip install requests

Per non dover inserire i comandi ogni volta, aggiungi le righe a ~/.bashrc o ~/.zshrc.

Windows (PowerShell)

# Temporaneamente (solo per la sessione corrente)
$env:HTTP_PROXY = "http://user:[email protected]:8080"
$env:HTTPS_PROXY = "http://user:[email protected]:8080"

# Permanentemente (per tutte le sessioni)
[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

Nota: se la password contiene caratteri speciali (@, #, %), devono essere URL-encoded. Ad esempio, @ diventa %40.

Flag --proxy direttamente in pip

Se hai bisogno di utilizzare un proxy solo per un comando, senza modificare le impostazioni globali:

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

# Per SOCKS5 è necessario il pacchetto pysocks
pip install pysocks
pip install scikit-learn --proxy socks5://user:[email protected]:1080

Configurazione del proxy tramite pip.conf e pip.ini

Se desideri che il proxy venga utilizzato automaticamente ad ogni esecuzione di pip — senza esportare manualmente le variabili — scrivilo nel file di configurazione di pip.

Posizione dei file di configurazione

Contenuto del file pip.conf

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

# Se è necessario ignorare la verifica SSL (non raccomandato in produzione)
# trusted-host = pypi.org
#                files.pythonhosted.org

Dopo aver salvato il file, tutte le chiamate successive a pip install utilizzeranno automaticamente il proxy specificato. Puoi controllare la configurazione attuale con il comando:

pip config list
pip config debug  # mostra tutti i file di configurazione e le loro priorità

Quale tipo di proxy scegliere per PyPI

Non tutti i proxy sono adatti per lavorare con PyPI. La scelta dipende dal motivo del blocco e dalla tua infrastruttura.

Per la maggior parte degli sviluppatori che affrontano il blocco di PyPI a causa di restrizioni regionali, la scelta ottimale saranno proxy di datacenter — offrono alta velocità di download dei pacchetti e connessione stabile. La velocità è particolarmente importante quando è necessario installare pacchetti pesanti come PyTorch o TensorFlow (diversi gigabyte).

Se gli IP dei datacenter sono bloccati anche nella tua regione (cosa che accade in caso di severe restrizioni statali), considera i proxy residenziali — utilizzano IP di utenti domestici reali e vengono bloccati molto meno frequentemente.

HTTP vs HTTPS vs SOCKS5: cosa supporta pip?

Pip supporta nativamente i proxy HTTP e HTTPS. Per SOCKS5 è necessario installare un pacchetto aggiuntivo:

# Per supportare SOCKS5 in pip è necessario pysocks
# Ma c'è un problema: pip è necessario per installare pysocks, e pip non funziona senza proxy
# Soluzione: prima installa tramite proxy HTTP, poi passa a SOCKS5

pip install pysocks --proxy http://1.2.3.4:8080
# Dopo questo puoi usare SOCKS5
pip install requests --proxy socks5://user:[email protected]:1080

Mirror di PyPI come alternativa al proxy

Se la configurazione del proxy sembra complicata o non hai un server proxy affidabile, puoi utilizzare mirror ufficiali e non ufficiali di PyPI. Questo è particolarmente rilevante per gli sviluppatori in Cina, dove ci sono diversi mirror locali veloci.

Mirror popolari di PyPI

Come utilizzare un mirror

# Una tantum, tramite il flag -i
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

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

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

Proxy per pip in Docker e CI/CD

Durante la costruzione delle immagini Docker, pip viene eseguito all'interno di un contenitore che potrebbe non avere accesso a PyPI. Questo è un problema particolarmente comune nei pipeline CI/CD aziendali (GitLab CI, GitHub Actions, Jenkins).

Passaggio del proxy tramite ARG nel Dockerfile

FROM python:3.11-slim

# Dichiarare ARG per il proxy
ARG HTTP_PROXY
ARG HTTPS_PROXY

# Passare in ENV per pip e altri strumenti
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

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

# Resettare il proxy dopo l'installazione (sicurezza)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

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

Costruzione con passaggio del proxy:

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

Impostazione globale del proxy per il daemon Docker

# 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

Importante: non hardcodificare mai le credenziali del proxy direttamente nei file YAML. Utilizza i segreti (Secrets) del tuo servizio CI/CD.

Configurazione del proxy per Poetry, conda e uv

I moderni progetti Python stanno sempre più utilizzando gestori di pacchetti alternativi. Esaminiamo la configurazione del proxy per ciascuno di essi.

Poetry

Poetry utilizza le variabili d'ambiente proprio come pip. Ma c'è una sfumatura: Poetry utilizza un proprio client HTTP basato su requests, quindi le variabili standard funzionano:

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

# Oppure configurazione della fonte in pyproject.toml
# [[tool.poetry.source]]
# name = "tsinghua"
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# priority = "primary"

conda / mamba

Conda ha un proprio sistema di configurazione:

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

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

# Mirror di conda per la Cina
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --set show_channel_urls yes

uv (nuovo gestore di pacchetti veloce)

uv di Astral è uno dei gestori di pacchetti più veloci per Python. Supporta anche le variabili d'ambiente standard:

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

# Oppure con il flag index
uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

pipenv

# pipenv eredita le variabili d'ambiente da pip
export HTTPS_PROXY=http://user:[email protected]:8080
pipenv install requests

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

Errori comuni e modi per risolverli

Esaminiamo i problemi più comuni che gli sviluppatori affrontano durante la configurazione del proxy per pip.

Errore 1: SSL Certificate Verification Failed

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

# Causa: il proxy aziendale sostituisce i certificati SSL (MITM)
# Soluzione 1: aggiungere il certificato CA aziendale
pip install requests --cert /path/to/corporate-ca.crt

# Soluzione 2: specificare il percorso del certificato in pip.conf
# [global]
# cert = /path/to/corporate-ca.crt

# Soluzione 3 (NON raccomandata per produzione): disabilitare la verifica SSL
pip install requests --trusted-host pypi.org --trusted-host files.pythonhosted.org

Errore 2: 407 Proxy Authentication Required

# Errore:
# ProxyError: 407 Proxy Authentication Required

# Causa: il proxy richiede autenticazione, ma le credenziali non sono state fornite
# Soluzione: assicurati che le credenziali siano codificate correttamente

# Se la password contiene caratteri speciali, codificali:
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"

Errore 3: pip ignora le variabili d'ambiente

# Controlla che le variabili siano impostate correttamente
echo $HTTPS_PROXY  # Linux/macOS
echo %HTTPS_PROXY%  # Windows cmd

# Controlla la priorità della configurazione di pip
pip config debug

# Possibile causa: l'ambiente virtuale non vede le variabili di sistema
# Soluzione: attiva venv e imposta nuovamente le variabili
source venv/bin/activate
export HTTPS_PROXY=http://1.2.3.4:8080
pip install package-name

Errore 4: Connection timeout anche tramite proxy

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

# Se il proxy non è disponibile — il problema è nel server proxy stesso
# Prova un'altra porta o protocollo

# Aumenta il timeout di pip
pip install package-name --timeout 120

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

Errore 5: Pacchetto installato, ma l'importazione non funziona

Questo non è correlato al proxy — molto probabilmente, il pacchetto è stato installato nel Python di sistema, non nell'ambiente virtuale attivo. Controlla:

which pip      # dovrebbe puntare a pip all'interno di venv
which python   # dovrebbe puntare a python all'interno di venv
pip show requests  # mostrerà dove è stato installato il pacchetto

Checklist di debug del proxy per pip

Conclusione

Il blocco di PyPI è un problema risolvibile, e ci sono diverse soluzioni affidabili. Per un avvio rapido, è sufficiente impostare la variabile HTTPS_PROXY e avviare pip come al solito. Per un funzionamento continuo — specificare il proxy in pip.conf. Per CI/CD — utilizzare segreti e ARG in Docker.

La scelta tra proxy e mirror dipende dal contesto: i mirror sono più veloci e più facili da configurare, ma richiedono fiducia nell'operatore del mirror. I proxy sono più versatili — funzionano non solo con PyPI, ma anche con qualsiasi altra risorsa bloccata (npm, Docker Hub, GitHub).

Se hai bisogno di un proxy affidabile per lavorare con PyPI, GitHub, Docker Hub e altre risorse bloccate nella tua regione, considera i proxy di datacenter — offrono alta velocità nel download di pacchetti pesanti e funzionano stabilmente negli ambienti CI/CD. Se nella tua regione sono bloccati anche gli IP dei datacenter, considera i proxy residenziali con IP di utenti domestici reali — vengono bloccati molto meno frequentemente.