PyPI用プロキシ：ブロックを回避してPythonパッケージをインストールする

```html

PyPIはPythonパッケージの主要なリポジトリであり、定期的にいくつかの国や企業ネットワークでブロックされます。もしpip installがハングしたり接続エラーを返したりする場合、それが原因です。この記事では、環境変数からミラーやDockerコンテナまで、すべての実行可能な方法を説明します。

なぜPyPIが利用できないのか: ブロックの理由

プロキシを設定する前に、どのようなブロックに直面しているのかを理解することが重要です。これによって解決策の選択が変わります。

地域的なブロック

一部の国（イラン、中国、制裁制限の期間中のロシアの一部地域）では、pypi.orgおよびfiles.pythonhosted.orgへのアクセスがプロバイダーや政府のファイアウォールによってブロックされます。pip install requestsコマンドは単にハングするか、ConnectionErrorを返します。

企業のプロキシとファイアウォール

多くの企業は、すべてのアウトバウンドトラフィックを企業プロキシサーバーを介してルーティングします。もしpipがこのプロキシを知らない場合、直接接続を試みて拒否されます。この場合の典型的なエラーは、ProxyError: HTTPSConnectionPool(host='pypi.org', port=443)です。

インターネットに接続されていないサーバー（エアギャップ）

生産サーバー、銀行のサーバー、政府機関のサーバー、または隔離されたクラウドVPC内のサーバーは、通常、インターネットへの直接アクセスを持っていません。ここでは、ネットワーク内のプロキシサーバーまたはローカルのPyPIミラーが必要です。

一時的な障害とレート制限

時々、PyPIは特定のIPからのリクエスト数を制限します — 特に同時に多数のDockerコンテナを展開している場合。この場合、IPローテーションを行うプロキシが問題を解決します。

PyPIがブロックされているかどうかを確認するには？

ターミナルで次のコマンドを実行します: curl -v https://pypi.org/simple/。接続がハングするか、SSL/タイムアウトエラーが発生する場合 — あなたのIPからはPyPIが利用できません。エラーに407 Proxy Authentication Requiredという単語が含まれている場合 — あなたは企業プロキシの背後にいます。

環境変数: 最も迅速な方法

最も簡単で汎用的な方法は、標準の環境変数HTTP_PROXYとHTTPS_PROXYを設定することです。Pipは、他の多くのPythonライブラリ（requests、urllib3）と同様に、追加の設定なしで自動的にこれらを取得します。

LinuxおよびmacOS

# 認証なし
export HTTP_PROXY="http://1.2.3.4:8080"
export HTTPS_PROXY="http://1.2.3.4:8080"

# ユーザー名とパスワードを含む
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"

# SOCKS5プロキシ
export HTTP_PROXY="socks5://user:[email protected]:1080"
export HTTPS_PROXY="socks5://user:[email protected]:1080"

# これでパッケージをインストールします
pip install requests

毎回コマンドを入力しないように、~/.bashrcまたは~/.zshrcに行を追加してください。

Windows (PowerShell)

# 一時的に（現在のセッションのみ）
$env:HTTP_PROXY = "http://user:[email protected]:8080"
$env:HTTPS_PROXY = "http://user:[email protected]:8080"

# 永続的に（すべてのセッション用）
[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

注意: パスワードに特殊文字（@、#、%）が含まれている場合、それらをURLエンコードする必要があります。例えば、@は%40に変わります。

--proxyフラグをpipに直接指定

グローバル設定を変更せずに、特定のコマンドのみにプロキシを使用する必要がある場合:

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

# SOCKS5にはpysocksパッケージが必要です
pip install pysocks
pip install scikit-learn --proxy socks5://user:[email protected]:1080

pip.confとpip.iniを介したプロキシの設定

pipを実行するたびに自動的にプロキシを使用するようにしたい場合 — 手動で環境変数をエクスポートすることなく、プロキシをpipの設定ファイルに記述します。

設定ファイルの場所

OS	ファイルパス	スコープ
Linux / macOS	`~/.config/pip/pip.conf`	現在のユーザー
Linux / macOS	`/etc/pip.conf`	システムのすべてのユーザー
Windows	`%APPDATA%\pip\pip.ini`	現在のユーザー
任意のOS	`./pip.conf`（プロジェクトフォルダー内）	現在のプロジェクトのみ

pip.confファイルの内容

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

# SSL検証を無視する必要がある場合（本番環境では推奨されません）
# trusted-host = pypi.org
#                files.pythonhosted.org

ファイルを保存した後、すべての後続のpip install呼び出しは自動的に指定されたプロキシを使用します。現在の設定を確認するには、次のコマンドを実行します:

pip config list
pip config debug  # すべての設定ファイルとその優先順位を表示します

PyPIに適したプロキシの種類

すべてのプロキシがPyPIでの作業に同じように適しているわけではありません。選択はブロックの理由とあなたのインフラストラクチャに依存します。

プロキシの種類	速度	信頼性	最適なシナリオ
データセンター	⚡ 高速	中程度	企業ネットワーク、CI/CD、大きなパッケージのダウンロード
住宅	中程度	⭐ 高い	地域的なブロック、データセンターIPもブロックされている場合
モバイル	中程度	⭐ 高い	厳しい地域的なブロック、最大限の回避が必要な場合
SOCKS5	⚡ 高速	高い	すべてのトラフィックを含むプロキシが必要な場合、DNSも含む

地域的な制限に直面している開発者にとって、最適な選択肢はデータセンターのプロキシです — これによりパッケージのダウンロード速度が向上し、安定した接続が保証されます。速度は、PyTorchやTensorFlowのような数ギガバイトの重いパッケージをインストールする際に特に重要です。

もしデータセンターのIPもあなたの地域でブロックされている場合（厳しい政府の制限がある場合）、住宅プロキシを検討してください — これらは実際の家庭ユーザーのIPを使用し、ブロックされる可能性がはるかに低くなります。

HTTP vs HTTPS vs SOCKS5: pipは何をサポートしていますか？

PipはHTTPおよびHTTPSプロキシをネイティブにサポートしています。SOCKS5を使用するには、追加のパッケージをインストールする必要があります:

# pipでSOCKS5をサポートするにはpysocksが必要です
# しかし問題があります: pipはpysocksをインストールするために必要で、pipはプロキシなしでは動作しません
# 解決策: まずHTTPプロキシを介してインストールし、その後SOCKS5に切り替えます

pip install pysocks --proxy http://1.2.3.4:8080
# その後SOCKS5を使用できます
pip install requests --proxy socks5://user:[email protected]:1080

プロキシの代替としてのPyPIミラー

プロキシの設定が難しいと感じたり、信頼できるプロキシサーバーがない場合は、公式および非公式のPyPIミラーを使用できます。これは特に中国の開発者にとって重要で、いくつかの高速なローカルミラーがあります。

ミラー	URL	地域 / オペレーター
清華大学	`https://pypi.tuna.tsinghua.edu.cn/simple`	中国（清華大学）
Aliyun	`https://mirrors.aliyun.com/pypi/simple`	中国（Alibaba Cloud）
USTC	`https://pypi.mirrors.ustc.edu.cn/simple`	中国（USTC）
Huawei Cloud	`https://repo.huaweicloud.com/repository/pypi/simple`	中国（Huawei）

ミラーを使用する方法

# 一度だけ、-iフラグを使用して
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

# 永続的に、pip.confを介して
# [global]
# index-url = https://pypi.tuna.tsinghua.edu.cn/simple
# trusted-host = pypi.tuna.tsinghua.edu.cn

# 複数のソース（フォールバック）
pip install pandas \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --extra-index-url https://pypi.org/simple/

⚠️ ミラーのセキュリティに関する重要事項

信頼できる大規模な組織（大学、クラウドプロバイダー）からの確認済みのミラーのみを使用してください。未知のミラーには、悪意のあるコードを含む改変されたパッケージが含まれている可能性があります — これはサプライチェーン攻撃と呼ばれます。重要なプロジェクトには、devpiやbandersnatchを使用して独自のミラーを立てることをお勧めします。

DockerおよびCI/CDにおけるpip用プロキシ

Dockerイメージをビルドする際、pipはコンテナ内で実行され、PyPIへのアクセスがない場合があります。これは企業のCI/CDパイプライン（GitLab CI、GitHub Actions、Jenkins）で特に一般的な問題です。

DockerfileでARGを介してプロキシを渡す

FROM python:3.11-slim

# プロキシ用のARGを宣言
ARG HTTP_PROXY
ARG HTTPS_PROXY

# pipや他のツール用にENVに渡す
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

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

# インストール後にプロキシをリセット（セキュリティのため）
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

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

プロキシを渡してビルドします:

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

Dockerデーモンのためのグローバルプロキシ設定

# ファイル: ~/.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

注意: YAMLファイルにプロキシの資格情報をハードコードしないでください。CI/CDサービスのシークレットを使用してください。

Poetry、conda、uvのためのプロキシの設定

現代のPythonプロジェクトはますます代替パッケージマネージャーを使用しています。それぞれの設定方法を見てみましょう。

Poetry

Poetryはpipと同様に環境変数を使用します。しかし、Poetryはrequestsに基づく独自のHTTPクライアントを使用しているため、標準の変数が機能します:

# Poetryで動作します
export HTTPS_PROXY=http://user:[email protected]:8080
poetry install

# またはpyproject.tomlでソースを設定
# [[tool.poetry.source]]
# name = "tsinghua"
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# priority = "primary"

conda / mamba

condaには独自の設定システムがあります:

# コマンドを介して
conda config --set proxy_servers.http http://user:[email protected]:8080
conda config --set proxy_servers.https http://user:[email protected]:8080

# または直接~/.condarcに
# proxy_servers:
#   http: http://user:[email protected]:8080
#   https: http://user:[email protected]:8080

# 中国のためのcondaミラー
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --set show_channel_urls yes

uv（新しい高速パッケージマネージャー）

uvはAstralによるPython用の最も高速なパッケージマネージャーの一つです。標準の環境変数もサポートしています:

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

# またはindexフラグを使用して
uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

pipenv

# pipenvはpipから環境変数を継承します
export HTTPS_PROXY=http://user:[email protected]:8080
pipenv install requests

# Pipfileでソースを変更
# [[source]]
# url = "https://pypi.tuna.tsinghua.edu.cn/simple"
# verify_ssl = true
# name = "tsinghua"

一般的なエラーとその解決方法

pipのプロキシ設定時に開発者が直面する最も一般的な問題を見てみましょう。

エラー1: SSL証明書の検証に失敗しました

# エラー:
# SSL: CERTIFICATE_VERIFY_FAILED] 証明書の検証に失敗しました: ローカル発行者証明書を取得できませんでした

# 原因: 企業プロキシがSSL証明書を置き換えています（MITM）
# 解決策1: 企業のCA証明書を追加します
pip install requests --cert /path/to/corporate-ca.crt

# 解決策2: pip.confに証明書のパスを指定します
# [global]
# cert = /path/to/corporate-ca.crt

# 解決策3（本番環境では推奨されません）: SSL検証を無効にします
pip install requests --trusted-host pypi.org --trusted-host files.pythonhosted.org

エラー2: 407 Proxy Authentication Required

# エラー:
# ProxyError: 407 Proxy Authentication Required

# 原因: プロキシが認証を要求していますが、ログイン/パスワードが渡されていません
# 解決策: 資格情報が正しくエンコードされていることを確認してください

# パスワードに特殊文字が含まれている場合、エンコードします:
python3 -c "from urllib.parse import quote; print(quote('my@pass#word'))"
# 出力: my%40pass%23word

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

エラー3: pipが環境変数を無視しています

# 環境変数が正しく設定されていることを確認します
echo $HTTPS_PROXY  # Linux/macOS
echo %HTTPS_PROXY%  # Windows cmd

# pipの設定の優先順位を確認します
pip config debug

# 可能な原因: 仮想環境がシステム変数を認識していません
# 解決策: venvをアクティブにして変数を再設定します
source venv/bin/activate
export HTTPS_PROXY=http://1.2.3.4:8080
pip install package-name

エラー4: プロキシ経由でも接続タイムアウト

# プロキシの可用性を確認します
curl -v --proxy http://user:[email protected]:8080 https://pypi.org/simple/

# プロキシが利用できない場合 — 問題はプロキシサーバー自体にあります
# 別のポートまたはプロトコルを試してください

# pipのタイムアウトを増やします
pip install package-name --timeout 120

# またはpip.confで:
# [global]
# timeout = 120

エラー5: パッケージはインストールされましたが、インポートが機能しません

これはプロキシとは関係ありません — おそらくパッケージはシステムPythonにインストールされており、アクティブな仮想環境にはインストールされていません。確認してください:

which pip      # venv内のpipを指している必要があります
which python   # venv内のpythonを指している必要があります
pip show requests  # パッケージがどこにインストールされたかを表示します

pipのプロキシ設定のデバッグチェックリスト

ステップバイステップの診断:

プロキシなしでPyPIの可用性を確認します: curl https://pypi.org
プロキシサーバーが動作していることを確認します: curl --proxy http://1.2.3.4:8080 https://pypi.org
環境変数を確認します: env | grep -i proxy
pipの設定を確認します: pip config debug
フラグを直接試します: pip install pkg --proxy http://... -v
SSLエラーがある場合 — 企業のCA証明書を確認します
それでも動作しない場合 — プロキシの代わりにミラーを試します

結論

PyPIのブロックは解決可能な問題であり、いくつかの信頼できる解決策があります。迅速に開始するには、HTTPS_PROXYを設定し、通常通りpipを実行します。恒久的に機能させるには、プロキシをpip.confに記述します。CI/CDでは、シークレットとDockerのARGを使用します。

プロキシとミラーの選択は文脈によります: ミラーはより速く、設定が簡単ですが、ミラーのオペレーターへの信頼が必要です。プロキシはより汎用的で、PyPIだけでなく、他のブロックされたリソース（npm、Docker Hub、GitHub）でも機能します。

PyPI、GitHub、Docker Hub、その他のブロックされたリソースで信頼できるプロキシが必要な場合は、データセンターのプロキシを検討してください — これにより重いパッケージのダウンロード速度が向上し、CI/CD環境で安定して動作します。もしあなたの地域でデータセンターのIPさえもブロックされている場合は、実際の家庭ユーザーのIPを持つ住宅プロキシを検討してください — これらは地域的なブロックに遭遇する可能性がはるかに低くなります。

PyPIのプロキシ：pipを使用して制限された地域でPythonパッケージをインストールする方法