Proxy untuk PyPI: cara menginstal paket Python di wilayah yang diblokir melalui pip

```html

PyPI — repositori utama paket Python — secara berkala diblokir di sejumlah negara dan jaringan perusahaan. Jika pip install macet atau memberikan kesalahan koneksi, masalahnya ada di sini. Dalam artikel ini, kita akan membahas semua cara yang berfungsi: dari variabel lingkungan hingga mirror dan kontainer Docker.

Mengapa PyPI tidak tersedia: alasan pemblokiran

Sebelum mengatur proxy, penting untuk memahami jenis pemblokiran yang Anda hadapi. Ini akan mempengaruhi pilihan solusi.

Pemblokiran regional

Di beberapa negara (Iran, China, beberapa wilayah Rusia selama periode pembatasan sanksi), akses ke pypi.org dan files.pythonhosted.org diblokir di tingkat penyedia atau firewall pemerintah. Perintah pip install requests hanya macet atau memberikan ConnectionError.

Proxy dan firewall perusahaan

Banyak perusahaan mengarahkan semua lalu lintas keluar melalui server proxy perusahaan. Jika pip tidak mengetahui tentang proxy ini, ia mencoba untuk terhubung secara langsung dan mendapatkan penolakan. Kesalahan tipikal dalam kasus ini: ProxyError: HTTPSConnectionPool(host='pypi.org', port=443).

Server tanpa akses internet (air-gapped)

Server produksi, server di bank, lembaga pemerintah, atau di VPC cloud yang terisolasi sering kali tidak memiliki akses langsung ke internet. Di sini dibutuhkan baik server proxy di dalam jaringan atau mirror lokal PyPI.

Gangguan sementara dan pembatasan laju

Terkadang PyPI sendiri membatasi jumlah permintaan dari satu IP — terutama jika Anda menjalankan puluhan kontainer Docker secara bersamaan. Dalam hal ini, proxy dengan rotasi IP menyelesaikan masalah.

Bagaimana cara memeriksa apakah PyPI diblokir?

Jalankan di terminal: curl -v https://pypi.org/simple/. Jika koneksi macet atau memberikan kesalahan SSL/timeout — PyPI tidak tersedia dari IP Anda. Jika kesalahan mengandung kata 407 Proxy Authentication Required — Anda berada di belakang proxy perusahaan.

Variabel lingkungan: cara tercepat

Cara yang paling sederhana dan universal adalah dengan mengatur variabel lingkungan standar HTTP_PROXY dan HTTPS_PROXY. Pip, seperti sebagian besar pustaka Python (requests, urllib3), secara otomatis akan mengambilnya tanpa pengaturan tambahan.

Linux dan macOS

# Tanpa autentikasi
export HTTP_PROXY="http://1.2.3.4:8080"
export HTTPS_PROXY="http://1.2.3.4:8080"

# Dengan login dan 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"

# Sekarang kita menginstal paket
pip install requests

Agar tidak perlu memasukkan perintah setiap kali, tambahkan baris tersebut ke ~/.bashrc atau ~/.zshrc.

Windows (PowerShell)

# Sementara (hanya untuk sesi saat ini)
$env:HTTP_PROXY = "http://user:[email protected]:8080"
$env:HTTPS_PROXY = "http://user:[email protected]:8080"

# Permanen (untuk semua sesi)
[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

Harap diperhatikan: jika password mengandung karakter khusus (@, #, %), mereka perlu di-URL-encode. Misalnya, @ menjadi %40.

Flag --proxy langsung di pip

Jika Anda perlu menggunakan proxy hanya untuk satu perintah, tanpa mengubah pengaturan global:

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

# Untuk SOCKS5, paket pysocks diperlukan
pip install pysocks
pip install scikit-learn --proxy socks5://user:[email protected]:1080

Mengatur proxy melalui pip.conf dan pip.ini

Jika Anda ingin proxy digunakan secara otomatis setiap kali pip dijalankan — tanpa mengekspor variabel secara manual — tuliskan di file konfigurasi pip.

Lokasi file konfigurasi

Isi file pip.conf

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

# Jika perlu mengabaikan verifikasi SSL (tidak disarankan di produksi)
# trusted-host = pypi.org
#                files.pythonhosted.org

Setelah menyimpan file, semua panggilan berikutnya ke pip install akan secara otomatis menggunakan proxy yang ditentukan. Untuk memeriksa konfigurasi saat ini, gunakan perintah:

pip config list
pip config debug  # menunjukkan semua file konfigurasi dan prioritasnya

Jenis proxy mana yang harus dipilih untuk PyPI

Tidak semua proxy cocok untuk bekerja dengan PyPI. Pilihan tergantung pada alasan pemblokiran dan infrastruktur Anda.

Untuk sebagian besar pengembang yang menghadapi pemblokiran PyPI karena pembatasan regional, pilihan terbaik adalah proxy datacenter — mereka menawarkan kecepatan tinggi untuk mengunduh paket dan koneksi yang stabil. Kecepatan sangat penting ketika Anda perlu menginstal paket berat seperti PyTorch atau TensorFlow (beberapa gigabyte).

Namun, jika IP datacenter juga diblokir di wilayah Anda (ini terjadi pada pembatasan pemerintah yang ketat), pertimbangkan proxy residensial — mereka menggunakan IP pengguna rumah yang nyata dan jauh lebih jarang terkena pemblokiran.

HTTP vs HTTPS vs SOCKS5: apa yang didukung pip?

Pip secara native mendukung proxy HTTP dan HTTPS. Untuk SOCKS5, Anda perlu menginstal paket tambahan:

# Untuk mendukung SOCKS5 di pip, diperlukan pysocks
# Tetapi ada masalah: pip diperlukan untuk menginstal pysocks, dan pip tidak berfungsi tanpa proxy
# Solusi: pertama instal melalui proxy HTTP, kemudian beralih ke SOCKS5

pip install pysocks --proxy http://1.2.3.4:8080
# Setelah itu, Anda dapat menggunakan SOCKS5
pip install requests --proxy socks5://user:[email protected]:1080

Mirror PyPI sebagai alternatif proxy

Jika pengaturan proxy tampak rumit atau Anda tidak memiliki server proxy yang dapat diandalkan, Anda dapat menggunakan mirror resmi dan tidak resmi PyPI. Ini sangat relevan bagi pengembang di China, di mana ada beberapa mirror lokal yang cepat.

Mirror PyPI yang populer

Cara menggunakan mirror

# Sekali, melalui flag -i
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

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

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

Proxy untuk pip di Docker dan CI/CD

Saat membangun gambar Docker, pip dijalankan di dalam kontainer, yang mungkin tidak memiliki akses ke PyPI. Ini adalah masalah yang sangat umum di pipeline CI/CD perusahaan (GitLab CI, GitHub Actions, Jenkins).

Meneruskan proxy melalui ARG di Dockerfile

FROM python:3.11-slim

# Mendeklarasikan ARG untuk proxy
ARG HTTP_PROXY
ARG HTTPS_PROXY

# Meneruskan ke ENV untuk pip dan alat lainnya
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

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

# Menghapus proxy setelah instalasi (keamanan)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

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

Membangun dengan meneruskan proxy:

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

Pengaturan global proxy untuk 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

Penting: jangan pernah hardcode kredensial proxy langsung di file YAML. Gunakan rahasia (Secrets) dari layanan CI/CD Anda.

Mengatur proxy untuk Poetry, conda, dan uv

Proyek Python modern semakin sering menggunakan manajer paket alternatif. Mari kita lihat pengaturan proxy untuk masing-masing dari mereka.

Poetry

Poetry menggunakan variabel lingkungan sama seperti pip. Namun ada nuansa — Poetry menggunakan klien HTTP sendiri yang berbasis requests, sehingga variabel standar berfungsi:

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

# Atau pengaturan sumber di pyproject.toml
# [[tool.poetry.source]]
# name = "tsinghua"
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# priority = "primary"

conda / mamba

Conda memiliki sistem konfigurasinya sendiri:

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

# Atau langsung di ~/.condarc
# proxy_servers:
#   http: http://user:[email protected]:8080
#   https: http://user:[email protected]:8080

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

uv (manajer paket cepat baru)

uv dari Astral — salah satu manajer paket tercepat untuk Python. Ini juga mendukung variabel lingkungan standar:

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

# Atau dengan flag index
uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

pipenv

# pipenv mewarisi variabel lingkungan dari pip
export HTTPS_PROXY=http://user:[email protected]:8080
pipenv install requests

# Mengubah sumber di Pipfile
# [[source]]
# url = "https://pypi.tuna.tsinghua.edu.cn/simple"
# verify_ssl = true
# name = "tsinghua"

Kesalahan umum dan cara mengatasinya

Mari kita bahas masalah yang paling umum dihadapi pengembang saat mengatur proxy untuk pip.

Kesalahan 1: SSL Certificate Verification Failed

# Kesalahan:
# SSL: CERTIFICATE_VERIFY_FAILED] verifikasi sertifikat gagal: tidak dapat mendapatkan sertifikat penerbit lokal

# Alasan: proxy perusahaan mengganti sertifikat SSL (MITM)
# Solusi 1: tambahkan sertifikat CA perusahaan
pip install requests --cert /path/to/corporate-ca.crt

# Solusi 2: tentukan jalur ke sertifikat di pip.conf
# [global]
# cert = /path/to/corporate-ca.crt

# Solusi 3 (TIDAK disarankan untuk produksi): nonaktifkan verifikasi SSL
pip install requests --trusted-host pypi.org --trusted-host files.pythonhosted.org

Kesalahan 2: 407 Proxy Authentication Required

# Kesalahan:
# ProxyError: 407 Proxy Authentication Required

# Alasan: proxy memerlukan autentikasi, tetapi login/password tidak diberikan
# Solusi: pastikan kredensial dikodekan dengan benar

# Jika password mengandung karakter khusus, kodekan:
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"

Kesalahan 3: pip mengabaikan variabel lingkungan

# Periksa bahwa variabel diatur dengan benar
echo $HTTPS_PROXY  # Linux/macOS
echo %HTTPS_PROXY%  # Windows cmd

# Periksa prioritas konfigurasi pip
pip config debug

# Kemungkinan penyebab: lingkungan virtual tidak melihat variabel sistem
# Solusi: aktifkan venv dan atur variabel lagi
source venv/bin/activate
export HTTPS_PROXY=http://1.2.3.4:8080
pip install package-name

Kesalahan 4: Connection timeout bahkan melalui proxy

# Periksa ketersediaan proxy
curl -v --proxy http://user:[email protected]:8080 https://pypi.org/simple/

# Jika proxy tidak tersedia — masalah ada pada server proxy itu sendiri
# Coba port atau protokol lain

# Tingkatkan timeout pip
pip install package-name --timeout 120

# Atau di pip.conf:
# [global]
# timeout = 120

Kesalahan 5: Paket terinstal, tetapi impor tidak berfungsi

Ini tidak terkait dengan proxy — kemungkinan besar, paket terinstal di Python sistem, bukan di lingkungan virtual yang aktif. Periksa:

which pip      # harus menunjuk ke pip di dalam venv
which python   # harus menunjuk ke python di dalam venv
pip show requests  # akan menunjukkan ke mana paket diinstal

Daftar periksa pemecahan masalah proxy untuk pip

Kesimpulan

Pemblokiran PyPI adalah masalah yang dapat diatasi, dan ada beberapa solusi yang dapat diandalkan. Untuk memulai dengan cepat, cukup atur variabel HTTPS_PROXY dan jalankan pip seperti biasa. Untuk operasi yang berkelanjutan — tuliskan proxy di pip.conf. Untuk CI/CD — gunakan rahasia dan ARG di Docker.

Pilihan antara proxy dan mirror tergantung pada konteks: mirror lebih cepat dan lebih mudah untuk diatur, tetapi memerlukan kepercayaan pada operator mirror. Proxy lebih universal — ia bekerja tidak hanya dengan PyPI, tetapi juga dengan semua sumber daya lain yang diblokir (npm, Docker Hub, GitHub).

Jika Anda memerlukan proxy yang andal untuk bekerja dengan PyPI, GitHub, Docker Hub, dan sumber daya lain yang diblokir di wilayah Anda, pertimbangkan proxy datacenter — mereka menawarkan kecepatan tinggi saat mengunduh paket berat dan berfungsi stabil di lingkungan CI/CD. Namun, jika di wilayah Anda bahkan IP datacenter diblokir, pertimbangkan proxy residensial dengan IP pengguna rumah yang nyata — mereka jauh lebih jarang terkena pemblokiran regional.