Proxys für PyPI: So installieren Sie Python-Pakete in gesperrten Regionen über pip

```html

PyPI — das Hauptrepository für Python-Pakete — wird in einer Reihe von Ländern und Unternehmensnetzwerken gelegentlich blockiert. Wenn pip install hängt oder einen Verbindungsfehler ausgibt, liegt das genau daran. In diesem Artikel werden alle funktionierenden Methoden behandelt: von Umgebungsvariablen über Mirrors bis hin zu Docker-Containern.

Warum ist PyPI nicht verfügbar: Gründe für Blockaden

Bevor Sie einen Proxy einrichten, ist es wichtig zu verstehen, mit welcher Art von Blockade Sie konfrontiert sind. Dies beeinflusst die Wahl der Lösung.

Regionale Blockaden

In mehreren Ländern (Iran, China, einige Regionen Russlands während der Zeit von Sanktionen) wird der Zugang zu pypi.org und files.pythonhosted.org auf Anbieterebene oder durch staatliche Firewalls blockiert. Der Befehl pip install requests hängt einfach oder gibt einen ConnectionError aus.

Unternehmensproxys und Firewalls

Viele Unternehmen leiten den gesamten ausgehenden Datenverkehr über einen Unternehmensproxy-Server. Wenn pip nichts über diesen Proxy weiß, versucht es, direkt zu verbinden und erhält eine Ablehnung. Ein typischer Fehler in diesem Fall lautet: ProxyError: HTTPSConnectionPool(host='pypi.org', port=443).

Server ohne Internetzugang (air-gapped)

Produktionsserver, Server in Banken, staatlichen Einrichtungen oder in isolierten Cloud-VPCs haben oft keinen direkten Zugang zum Internet. Hier wird entweder ein Proxy-Server innerhalb des Netzwerks oder ein lokales PyPI-Mirror benötigt.

Temporäre Ausfälle und Rate-Limiting

Manchmal begrenzt PyPI selbst die Anzahl der Anfragen von einer IP — insbesondere wenn Sie Dutzende von Docker-Containern gleichzeitig bereitstellen. In diesem Fall löst ein Proxy mit IP-Rotation das Problem.

Wie überprüft man, ob PyPI blockiert ist?

Führen Sie im Terminal aus: curl -v https://pypi.org/simple/. Wenn die Verbindung hängt oder einen SSL-/Timeout-Fehler ausgibt — PyPI ist von Ihrer IP aus nicht verfügbar. Wenn der Fehler das Wort 407 Proxy Authentication Required enthält — Sie befinden sich hinter einem Unternehmensproxy.

Umgebungsvariablen: der schnellste Weg

Der einfachste und universellste Weg ist, die Standard-Umgebungsvariablen HTTP_PROXY und HTTPS_PROXY zu setzen. Pip, wie die meisten Python-Bibliotheken (requests, urllib3), übernimmt diese automatisch ohne zusätzliche Konfiguration.

Linux und macOS

# Ohne Authentifizierung
export HTTP_PROXY="http://1.2.3.4:8080"
export HTTPS_PROXY="http://1.2.3.4:8080"

# Mit Benutzername und Passwort
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"

# Jetzt Paket installieren
pip install requests

Um die Befehle nicht jedes Mal eingeben zu müssen, fügen Sie die Zeilen in ~/.bashrc oder ~/.zshrc hinzu.

Windows (PowerShell)

# Vorübergehend (nur für die aktuelle Sitzung)
$env:HTTP_PROXY = "http://user:[email protected]:8080"
$env:HTTPS_PROXY = "http://user:[email protected]:8080"

# Dauerhaft (für alle Sitzungen)
[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

Bitte beachten Sie: Wenn das Passwort spezielle Zeichen enthält (@, #, %), müssen diese URL-kodiert werden. Zum Beispiel wird @ zu %40.

Flag --proxy direkt in pip

Wenn Sie den Proxy nur für einen Befehl verwenden möchten, ohne die globalen Einstellungen zu ändern:

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

# Für SOCKS5 wird das Paket pysocks benötigt
pip install pysocks
pip install scikit-learn --proxy socks5://user:[email protected]:1080

Proxy-Konfiguration über pip.conf und pip.ini

Wenn Sie möchten, dass der Proxy automatisch bei jedem Start von pip verwendet wird — ohne manuelles Exportieren der Variablen — tragen Sie ihn in die Konfigurationsdatei pip ein.

Standorte der Konfigurationsdateien

Inhalt der Datei pip.conf

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

# Wenn die SSL-Überprüfung ignoriert werden soll (nicht empfohlen in der Produktion)
# trusted-host = pypi.org
#                files.pythonhosted.org

Nach dem Speichern der Datei werden alle nachfolgenden Aufrufe von pip install automatisch den angegebenen Proxy verwenden. Die aktuelle Konfiguration kann mit dem Befehl überprüft werden:

pip config list
pip config debug  # zeigt alle Konfigurationsdateien und deren Prioritäten an

Welchen Proxy-Typ für PyPI wählen

Nicht alle Proxys sind gleich gut für die Arbeit mit PyPI geeignet. Die Wahl hängt von der Art der Blockade und Ihrer Infrastruktur ab.

Für die meisten Entwickler, die mit Blockaden von PyPI aufgrund regionaler Einschränkungen konfrontiert sind, sind Rechenzentrumsproxys die optimale Wahl — sie bieten hohe Downloadgeschwindigkeiten und eine stabile Verbindung. Geschwindigkeit ist besonders wichtig, wenn große Pakete wie PyTorch oder TensorFlow (mehrere Gigabyte) installiert werden müssen.

Wenn jedoch auch Rechenzentrums-IP in Ihrer Region blockiert sind (was bei strengen staatlichen Einschränkungen vorkommen kann), sollten Sie residential Proxys in Betracht ziehen — diese verwenden IPs von echten Haushaltsnutzern und sind deutlich seltener von Blockaden betroffen.

HTTP vs HTTPS vs SOCKS5: Was unterstützt pip?

Pip unterstützt nativ HTTP- und HTTPS-Proxys. Für SOCKS5 muss ein zusätzliches Paket installiert werden:

# Für die Unterstützung von SOCKS5 in pip wird pysocks benötigt
# Aber es gibt ein Problem: pip wird benötigt, um pysocks zu installieren, und pip funktioniert nicht ohne Proxy
# Lösung: Zuerst über HTTP-Proxy installieren, dann auf SOCKS5 umschalten

pip install pysocks --proxy http://1.2.3.4:8080
# Danach kann SOCKS5 verwendet werden
pip install requests --proxy socks5://user:[email protected]:1080

PyPI-Mirrors als Alternative zu Proxys

Wenn die Einrichtung eines Proxys kompliziert erscheint oder Sie keinen zuverlässigen Proxy-Server haben, können Sie offizielle und inoffizielle PyPI-Mirrors verwenden. Dies ist besonders relevant für Entwickler in China, wo es mehrere schnelle lokale Mirrors gibt.

Beliebte PyPI-Mirrors

Wie man einen Mirror verwendet

# Einmalig, über das Flag -i
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

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

# Mehrere Quellen (Fallback)
pip install pandas \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --extra-index-url https://pypi.org/simple/

Proxys für pip in Docker und CI/CD

Beim Erstellen von Docker-Images wird pip innerhalb eines Containers ausgeführt, der möglicherweise keinen Zugriff auf PyPI hat. Dies ist ein besonders häufiges Problem in Unternehmens-CI/CD-Pipelines (GitLab CI, GitHub Actions, Jenkins).

Übertragung des Proxys über ARG in Dockerfile

FROM python:3.11-slim

# Deklarieren Sie ARG für den Proxy
ARG HTTP_PROXY
ARG HTTPS_PROXY

# Übertragen in ENV für pip und andere Werkzeuge
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

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

# Proxy nach der Installation zurücksetzen (Sicherheit)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

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

Build mit Übertragung des Proxys:

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

Globale Proxy-Konfiguration für den Docker-Daemon

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

Wichtig: Hardcodieren Sie niemals die Proxy-Anmeldeinformationen direkt in YAML-Dateien. Verwenden Sie die Secrets Ihres CI/CD-Dienstes.

Proxy-Konfiguration für Poetry, conda und uv

Moderne Python-Projekte verwenden zunehmend alternative Paketmanager. Lassen Sie uns die Proxy-Konfiguration für jeden von ihnen betrachten.

Poetry

Poetry verwendet Umgebungsvariablen genauso wie pip. Aber es gibt einen Haken — Poetry verwendet einen eigenen HTTP-Client, der auf requests basiert, daher funktionieren die Standardvariablen:

# Funktioniert für Poetry
export HTTPS_PROXY=http://user:[email protected]:8080
poetry install

# Oder Konfiguration der Quelle in pyproject.toml
# [[tool.poetry.source]]
# name = "tsinghua"
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# priority = "primary"

conda / mamba

Bei conda gibt es ein eigenes Konfigurationssystem:

# Über den Befehl
conda config --set proxy_servers.http http://user:[email protected]:8080
conda config --set proxy_servers.https http://user:[email protected]:8080

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

# Conda-Mirror für China
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --set show_channel_urls yes

uv (neuer schneller Paketmanager)

uv von Astral ist einer der schnellsten Paketmanager für Python. Er unterstützt ebenfalls die Standard-Umgebungsvariablen:

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

# Oder mit dem Flag index
uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

pipenv

# pipenv erbt Umgebungsvariablen von pip
export HTTPS_PROXY=http://user:[email protected]:8080
pipenv install requests

# Quelle im Pipfile ändern
# [[source]]
# url = "https://pypi.tuna.tsinghua.edu.cn/simple"
# verify_ssl = true
# name = "tsinghua"

Häufige Fehler und deren Behebung

Lassen Sie uns die häufigsten Probleme betrachten, mit denen Entwickler bei der Proxy-Konfiguration für pip konfrontiert sind.

Fehler 1: SSL-Zertifikatüberprüfung fehlgeschlagen

# Fehler:
# SSL: CERTIFICATE_VERIFY_FAILED] Zertifikatüberprüfung fehlgeschlagen: lokales Ausstellerzertifikat konnte nicht abgerufen werden

# Grund: Unternehmensproxy ersetzt SSL-Zertifikate (MITM)
# Lösung 1: Unternehmens-CA-Zertifikat hinzufügen
pip install requests --cert /path/to/corporate-ca.crt

# Lösung 2: Pfad zum Zertifikat in pip.conf angeben
# [global]
# cert = /path/to/corporate-ca.crt

# Lösung 3 (NICHT empfohlen für die Produktion): SSL-Überprüfung deaktivieren
pip install requests --trusted-host pypi.org --trusted-host files.pythonhosted.org

Fehler 2: 407 Proxy-Authentifizierung erforderlich

# Fehler:
# ProxyError: 407 Proxy Authentication Required

# Grund: Proxy erfordert Authentifizierung, aber Benutzername/Passwort wurden nicht übergeben
# Lösung: Stellen Sie sicher, dass die Anmeldeinformationen korrekt kodiert sind

# Wenn das Passwort Sonderzeichen enthält, kodieren Sie diese:
python3 -c "from urllib.parse import quote; print(quote('my@pass#word'))"
# Ausgabe: my%40pass%23word

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

Fehler 3: pip ignoriert Umgebungsvariablen

# Überprüfen Sie, ob die Variablen korrekt gesetzt sind
echo $HTTPS_PROXY  # Linux/macOS
echo %HTTPS_PROXY%  # Windows cmd

# Überprüfen Sie die Priorität der pip-Konfiguration
pip config debug

# Möglicher Grund: Virtuelle Umgebung sieht die Systemvariablen nicht
# Lösung: Aktivieren Sie venv und setzen Sie die Variablen erneut
source venv/bin/activate
export HTTPS_PROXY=http://1.2.3.4:8080
pip install package-name

Fehler 4: Verbindungs-Timeout auch über Proxy

# Überprüfen Sie die Erreichbarkeit des Proxys
curl -v --proxy http://user:[email protected]:8080 https://pypi.org/simple/

# Wenn der Proxy nicht erreichbar ist — das Problem liegt am Proxy-Server selbst
# Versuchen Sie einen anderen Port oder ein anderes Protokoll

# Erhöhen Sie das Timeout von pip
pip install package-name --timeout 120

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

Fehler 5: Paket installiert, aber Import funktioniert nicht

Dies hat nichts mit dem Proxy zu tun — wahrscheinlich wurde das Paket im System-Python und nicht in der aktiven virtuellen Umgebung installiert. Überprüfen Sie:

which pip      # sollte auf pip innerhalb von venv zeigen
which python   # sollte auf python innerhalb von venv zeigen
pip show requests  # zeigt, wo das Paket installiert wurde

Checkliste zur Fehlersuche bei Proxys für pip

Fazit

Die Blockade von PyPI ist ein lösbares Problem, und es gibt mehrere zuverlässige Lösungen. Für einen schnellen Start reicht es aus, die Variable HTTPS_PROXY zu setzen und pip wie gewohnt zu starten. Für einen dauerhaften Betrieb — den Proxy in pip.conf eintragen. Für CI/CD — Secrets und ARG in Docker verwenden.

Die Wahl zwischen Proxy und Mirror hängt vom Kontext ab: Mirrors sind schneller und einfacher einzurichten, erfordern jedoch Vertrauen in den Betreiber des Mirrors. Proxys sind universeller — sie funktionieren nicht nur mit PyPI, sondern auch mit allen anderen blockierten Ressourcen (npm, Docker Hub, GitHub).

Wenn Sie einen zuverlässigen Proxy für die Arbeit mit PyPI, GitHub, Docker Hub und anderen blockierten Ressourcen in Ihrer Region benötigen, achten Sie auf Rechenzentrumsproxys — sie bieten hohe Geschwindigkeiten beim Herunterladen großer Pakete und funktionieren stabil in CI/CD-Umgebungen. Wenn jedoch in Ihrer Region sogar die IPs von Rechenzentren blockiert werden, sollten Sie residential Proxys mit IPs von echten Haushaltsnutzern in Betracht ziehen — diese sind deutlich seltener von regionalen Blockaden betroffen.