Proxies pour PyPI : comment installer des paquets Python dans des régions bloquées via pip

```html

PyPI — le principal dépôt de paquets Python — est périodiquement bloqué dans plusieurs pays et réseaux d'entreprise. Si pip install se fige ou renvoie une erreur de connexion, le problème vient de cela. Dans cet article, nous examinerons toutes les méthodes fonctionnelles : des variables d'environnement aux miroirs et conteneurs Docker.

Pourquoi PyPI est-il inaccessible : raisons des blocages

Avant de configurer un proxy, il est important de comprendre quel type de blocage vous rencontrez. Cela déterminera le choix de la solution.

Blocages régionaux

Dans plusieurs pays (Iran, Chine, certaines régions de Russie pendant les périodes de sanctions), l'accès à pypi.org et files.pythonhosted.org est bloqué au niveau du fournisseur ou du pare-feu gouvernemental. La commande pip install requests se fige simplement ou renvoie une ConnectionError.

Proxys d'entreprise et pare-feu

De nombreuses entreprises dirigent tout le trafic sortant via un serveur proxy d'entreprise. Si pip n'est pas au courant de ce proxy, il essaie de se connecter directement et reçoit un refus. Une erreur typique dans ce cas est : ProxyError: HTTPSConnectionPool(host='pypi.org', port=443).

Serveurs sans accès à Internet (air-gapped)

Les serveurs de production, les serveurs dans les banques, les structures gouvernementales ou dans des VPC cloud isolés n'ont souvent pas d'accès direct à Internet. Ici, un serveur proxy interne ou un miroir local de PyPI est nécessaire.

Pannes temporaires et limitation de débit

Parfois, PyPI limite lui-même le nombre de requêtes d'une seule IP — surtout si vous déployez des dizaines de conteneurs Docker simultanément. Dans ce cas, un proxy avec rotation d'IP résout le problème.

Comment vérifier si PyPI est bloqué ?

Exécutez dans le terminal : curl -v https://pypi.org/simple/. Si la connexion se fige ou renvoie une erreur SSL/timeout — PyPI est inaccessible depuis votre IP. Si l'erreur contient le mot 407 Proxy Authentication Required — vous êtes derrière un proxy d'entreprise.

Variables d'environnement : le moyen le plus rapide

Le moyen le plus simple et le plus universel est de définir les variables d'environnement standard HTTP_PROXY et HTTPS_PROXY. Pip, comme la plupart des bibliothèques Python (requests, urllib3), les récupère automatiquement sans configuration supplémentaire.

Linux et macOS

# Sans authentification
export HTTP_PROXY="http://1.2.3.4:8080"
export HTTPS_PROXY="http://1.2.3.4:8080"

# Avec identifiant et mot de passe
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"

# Maintenant, installons le paquet
pip install requests

Pour ne pas avoir à entrer les commandes à chaque fois, ajoutez les lignes dans ~/.bashrc ou ~/.zshrc.

Windows (PowerShell)

# Temporairement (pour la session actuelle seulement)
$env:HTTP_PROXY = "http://user:[email protected]:8080"
$env:HTTPS_PROXY = "http://user:[email protected]:8080"

# De façon permanente (pour toutes les 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

Notez que si le mot de passe contient des caractères spéciaux (@, #, %), ils doivent être URL-encodés. Par exemple, @ devient %40.

Drapeau --proxy directement dans pip

Si vous devez utiliser un proxy uniquement pour une commande, sans modifier les paramètres globaux :

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

# Pour SOCKS5, le paquet pysocks est nécessaire
pip install pysocks
pip install scikit-learn --proxy socks5://user:[email protected]:1080

Configuration du proxy via pip.conf et pip.ini

Si vous souhaitez que le proxy soit utilisé automatiquement à chaque exécution de pip — sans exporter manuellement les variables — inscrivez-le dans le fichier de configuration pip.

Emplacement des fichiers de configuration

Contenu du fichier pip.conf

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

# Si vous devez ignorer la vérification SSL (non recommandé en production)
# trusted-host = pypi.org
#                files.pythonhosted.org

Après avoir enregistré le fichier, tous les appels suivants à pip install utiliseront automatiquement le proxy spécifié. Vous pouvez vérifier la configuration actuelle avec la commande :

pip config list
pip config debug  # montre tous les fichiers de configuration et leurs priorités

Quel type de proxy choisir pour PyPI

Tous les proxys ne conviennent pas de la même manière pour travailler avec PyPI. Le choix dépend de la raison du blocage et de votre infrastructure.

Pour la plupart des développeurs qui rencontrent des blocages de PyPI en raison de restrictions régionales, le choix optimal sera des proxys de datacenter — ils offrent une vitesse de téléchargement élevée des paquets et une connexion stable. La vitesse est particulièrement importante lorsque vous devez installer de gros paquets comme PyTorch ou TensorFlow (plusieurs gigaoctets).

Si les IP de datacenter sont également bloquées dans votre région (ce qui arrive lors de restrictions gouvernementales strictes), envisagez des proxys résidentiels — ils utilisent des IP de véritables utilisateurs domestiques et sont beaucoup moins souvent soumis à des blocages.

HTTP vs HTTPS vs SOCKS5 : que prend en charge pip ?

Pip prend en charge nativement les proxys HTTP et HTTPS. Pour SOCKS5, vous devez installer un paquet supplémentaire :

# Pour prendre en charge SOCKS5 dans pip, pysocks est nécessaire
# Mais il y a un problème : pip est nécessaire pour installer pysocks, et pip ne fonctionne pas sans proxy
# Solution : installez d'abord via un proxy HTTP, puis passez à SOCKS5

pip install pysocks --proxy http://1.2.3.4:8080
# Après cela, vous pouvez utiliser SOCKS5
pip install requests --proxy socks5://user:[email protected]:1080

Miroirs PyPI comme alternative au proxy

Si la configuration du proxy semble compliquée ou si vous n'avez pas de serveur proxy fiable, vous pouvez utiliser des miroirs PyPI officiels et non officiels. Cela est particulièrement pertinent pour les développeurs en Chine, où il existe plusieurs miroirs locaux rapides.

Miroirs PyPI populaires

Comment utiliser un miroir

# Une fois, via le drapeau -i
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

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

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

Proxy pour pip dans Docker et CI/CD

Lors de la construction d'images Docker, pip s'exécute à l'intérieur d'un conteneur qui peut ne pas avoir accès à PyPI. C'est un problème particulièrement fréquent dans les pipelines CI/CD d'entreprise (GitLab CI, GitHub Actions, Jenkins).

Passage du proxy via ARG dans Dockerfile

FROM python:3.11-slim

# Déclaration de l'ARG pour le proxy
ARG HTTP_PROXY
ARG HTTPS_PROXY

# Passer dans ENV pour pip et d'autres outils
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

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

# Réinitialiser le proxy après l'installation (sécurité)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

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

Construction avec passage du proxy :

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

Configuration globale du proxy pour le démon Docker

# Fichier : ~/.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: Installer les dépendances
        run: pip install -r requirements.txt

Important : ne jamais coder en dur les identifiants du proxy directement dans les fichiers YAML. Utilisez les secrets (Secrets) de votre service CI/CD.

Configuration du proxy pour Poetry, conda et uv

Les projets Python modernes utilisent de plus en plus des gestionnaires de paquets alternatifs. Examinons la configuration du proxy pour chacun d'eux.

Poetry

Poetry utilise les variables d'environnement de la même manière que pip. Mais il y a un détail — Poetry utilise son propre client HTTP basé sur requests, donc les variables standard fonctionnent :

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

# Ou configuration de la source dans pyproject.toml
# [[tool.poetry.source]]
# name = "tsinghua"
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# priority = "primary"

conda / mamba

Conda a son propre système de configuration :

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

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

# Miroir conda pour la Chine
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --set show_channel_urls yes

uv (nouveau gestionnaire de paquets rapide)

uv d'Astral est l'un des gestionnaires de paquets les plus rapides pour Python. Il prend également en charge les variables d'environnement standard :

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

# Ou avec le drapeau index
uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

pipenv

# pipenv hérite des variables d'environnement de pip
export HTTPS_PROXY=http://user:[email protected]:8080
pipenv install requests

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

Erreurs fréquentes et solutions

Examinons les problèmes les plus courants rencontrés par les développeurs lors de la configuration du proxy pour pip.

Erreur 1 : Échec de la vérification du certificat SSL

# Erreur :
# SSL: CERTIFICATE_VERIFY_FAILED] échec de la vérification du certificat : impossible d'obtenir le certificat émetteur local

# Raison : le proxy d'entreprise remplace les certificats SSL (MITM)
# Solution 1 : ajouter le certificat CA d'entreprise
pip install requests --cert /path/to/corporate-ca.crt

# Solution 2 : indiquer le chemin vers le certificat dans pip.conf
# [global]
# cert = /path/to/corporate-ca.crt

# Solution 3 (NON recommandé pour la production) : désactiver la vérification SSL
pip install requests --trusted-host pypi.org --trusted-host files.pythonhosted.org

Erreur 2 : 407 Proxy Authentication Required

# Erreur :
# ProxyError: 407 Proxy Authentication Required

# Raison : le proxy nécessite une authentification, mais l'identifiant/mot de passe n'ont pas été fournis
# Solution : assurez-vous que les identifiants sont correctement encodés

# Si le mot de passe contient des caractères spéciaux, encodez-les :
python3 -c "from urllib.parse import quote; print(quote('my@pass#word'))"
# Sortie : my%40pass%23word

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

Erreur 3 : pip ignore les variables d'environnement

# Vérifiez que les variables sont correctement définies
echo $HTTPS_PROXY  # Linux/macOS
echo %HTTPS_PROXY%  # Windows cmd

# Vérifiez la priorité de la configuration pip
pip config debug

# Raison possible : l'environnement virtuel ne voit pas les variables système
# Solution : activez venv et définissez à nouveau les variables
source venv/bin/activate
export HTTPS_PROXY=http://1.2.3.4:8080
pip install package-name

Erreur 4 : Délai de connexion même via le proxy

# Vérifiez la disponibilité du proxy
curl -v --proxy http://user:[email protected]:8080 https://pypi.org/simple/

# Si le proxy est inaccessible — le problème vient du serveur proxy lui-même
# Essayez un autre port ou protocole

# Augmentez le délai d'attente de pip
pip install package-name --timeout 120

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

Erreur 5 : Le paquet est installé, mais l'importation ne fonctionne pas

Cela n'est pas lié au proxy — il est probable que le paquet soit installé dans le Python système, et non dans l'environnement virtuel actif. Vérifiez :

which pip      # doit pointer vers pip à l'intérieur de venv
which python   # doit pointer vers python à l'intérieur de venv
pip show requests  # montrera où le paquet est installé

Liste de contrôle pour le dépannage du proxy pour pip

Conclusion

Le blocage de PyPI est un problème résoluble, et il existe plusieurs solutions fiables. Pour un démarrage rapide, il suffit de définir la variable HTTPS_PROXY et de lancer pip comme d'habitude. Pour un fonctionnement permanent — inscrivez le proxy dans pip.conf. Pour CI/CD — utilisez des secrets et ARG dans Docker.

Le choix entre un proxy et un miroir dépend du contexte : les miroirs sont plus rapides et plus simples à configurer, mais nécessitent de faire confiance à l'opérateur du miroir. Les proxys sont plus polyvalents — ils fonctionnent non seulement avec PyPI, mais aussi avec d'autres ressources bloquées (npm, Docker Hub, GitHub).

Si vous avez besoin d'un proxy fiable pour travailler avec PyPI, GitHub, Docker Hub et d'autres ressources bloquées dans votre région, envisagez des proxys de datacenter — ils offrent une vitesse élevée lors du téléchargement de gros paquets et fonctionnent de manière stable dans des environnements CI/CD. Si les IP des datacenters sont également bloquées dans votre région, envisagez des proxys résidentiels avec des IP de véritables utilisateurs domestiques — ils sont beaucoup moins souvent soumis à des blocages régionaux.