KAL
Menu

Virtual environment dan pip

Membuat virtual environment dengan venv, memasang paket dengan pip, dan disiplin isolasi.

Daftar isi

Virtual environment memberi setiap proyek Python lingkungan package yang terpisah, sedangkan pip adalah alat yang mengisi lingkungan tersebut dengan package dari PyPI. Tanpa pemisahan ini, pemasangan versi pustaka untuk satu proyek dapat merusak proyek lain yang berbagi interpreter utama. Topik ini membahas cara membuat virtual environment dengan modul venv, memasang package dengan pip, mencatat dependensi ke dalam requirements.txt, dan disiplin pemakaian yang menjaga lingkungan tetap bersih.

Memeriksa lingkungan tempat Python berjalan#

Sebelum mengelola lingkungan, keadaan interpreter yang sedang berjalan perlu diketahui. Atribut sys.prefix menunjuk direktori akar interpreter yang aktif, sedangkan sys.base_prefix menunjuk akar pemasangan Python utama. Pada interpreter utama kedua atribut bernilai sama, sedangkan pada interpreter yang berjalan di dalam virtual environment keduanya berbeda. Perbandingan tersebut menjadi cara pemeriksaan yang dapat diandalkan.

python Contoh: memeriksa apakah interpreter berada di dalam virtual environment 
import sys

print(sys.prefix == sys.base_prefix)
text Keluaran 
False

Keluaran False berarti interpreter tempat contoh ini dijalankan berada di dalam virtual environment, dan memang lingkungan sandbox untuk verifikasi topik ini berupa virtual environment. Pada pemasangan Python utama yang belum diberi lingkungan apa pun, perbandingan yang sama mencetak True. Pemeriksaan ini tidak bergantung pada prompt terminal, sehingga tetap benar ketika skrip dijalankan dari alat lain.

Membuat virtual environment#

Modul venv membuat lingkungan baru dengan perintah python3 -m venv <direktori>. Perintah itu menghasilkan satu direktori berisi interpreter yang menunjuk pemasangan Python utama, salinan pip, serta folder site-packages kosong yang menjadi tempat package milik lingkungan tersebut. Contoh berikut membuat satu lingkungan di direktori sementara dan memeriksa isinya.

bash 
# membersihkan sisa contoh sebelumnya bila ada
rm -rf /tmp/venv-contoh

# membuat virtual environment baru di /tmp/venv-contoh
python3 -m venv /tmp/venv-contoh

# memeriksa versi Python milik lingkungan baru
/tmp/venv-contoh/bin/python --version

# memeriksa package yang tersedia pada lingkungan yang baru
/tmp/venv-contoh/bin/python -m pip list
text Keluaran 
Python 3.12.16
Package Version
------- -------
pip     26.2.2

Interpreter di dalam lingkungan baru melaporkan versi Python yang sama dengan interpreter utama, tetapi daftar package-nya nyaris kosong dan hanya memuat pip sendiri. Struktur direktori yang dihasilkan perintah tersebut ringkas seperti berikut.

text 
venv-contoh/
├── bin/                     ← perintah python, pip, dan skrip activate
├── lib/
│   └── python3.12/
│       └── site-packages/   ← tempat pip memasang package
└── pyvenv.cfg               ← penanda bahwa ini virtual environment

Berkas pyvenv.cfg adalah yang membedakan lingkungan dari direktori biasa, karena di situlah interpreter membaca bahwa dirinya berjalan di dalam virtual environment. Konvensi umum menamai direktori lingkungan .venv di dalam folder proyek, sehingga setiap proyek membawa lingkungannya sendiri dan namanya tersembunyi dari daftar berkas biasa.

Mengaktifkan virtual environment#

Aktivasi menyesuaikan terminal yang sedang berjalan agar perintah python dan pip yang ditulis tanpa jalur menunjuk lingkungan yang dipilih. Skrip aktivasi berada di folder bin pada Linux dan macOS, serta di folder Scripts pada Windows. Contoh berikut mengaktifkan lingkungan yang dibuat sebelumnya.

bash 
# mengaktifkan virtual environment pada terminal bash
source /tmp/venv-contoh/bin/activate

# perintah python kini menunjuk interpreter milik lingkungan aktif
which python
python -m pip --version

# menonaktifkan kembali lingkungan tersebut
deactivate
text Keluaran 
/tmp/venv-contoh/bin/python
pip 26.2.2 from /tmp/venv-contoh/lib/python3.12/site-packages/pip (python 3.12)

Perintah which python menunjuk ke dalam lingkungan, dan pip yang dijalankan pun berasal dari site-packages miliknya. Aktivasi hanya mengubah PATH terminal yang bersangkutan, sehingga terminal lain tetap menggunakan lingkungan lamanya, dan deactivate mengembalikan keadaan semula.

Memasang package dengan pip#

Package dipasang dengan python3 -m pip install <nama>. Bentuk python3 -m pip menjamin pip yang berjalan adalah milik python3 yang aktif, sehingga package selalu terpasang pada lingkungan yang benar. pip menelusuri versi yang cocok, mengunduhnya dari PyPI, lalu membongkarnya ke site-packages lingkungan yang aktif.

bash 
# tidak-dijalankan (memerlukan koneksi internet untuk mengunduh dari PyPI)
# memasang package ke dalam virtual environment yang aktif
python3 -m pip install httpx

# memeriksa daftar package yang kini tersedia
python3 -m pip list

# menghapus package bila tidak diperlukan lagi
python3 -m pip uninstall httpx

Perintah pada blok tersebut tidak dijalankan di sini karena proses pemasangannya mengunduh berkas dari jaringan. Pada terminal yang terhubung internet, install httpx menampilkan progres unduhan lalu diakhiri pesan keberhasilan, pip list menampilkan httpx beserta ketergantungan yang ikut terpasang, dan uninstall menghapusnya kembali dari lingkungan yang sama.

Mencatat dependensi dengan requirements.txt#

Dependensi proyek dicatat pada berkas requirements.txt, yaitu daftar nama package beserta penentu versinya, sehingga lingkungan yang sama dapat dibangun ulang di mesin mana pun.

text requirements.txt 
# Dependensi contoh aplikasi pengolah nilai
rich>=13.7
httpx>=0.27
pydantic>=2.7

Penentu >= menyatakan batas minimum dan membiarkan pip memilih versi terbaru yang cocok, sedangkan penentu == mengunci versi persis. Dua pola tersebut dipadukan oleh perintah freeze dan install -r. Perintah freeze menyalin seluruh isi lingkungan beserta versi terpasangnya ke dalam berkas dengan format ==, sedangkan install -r membacanya kembali.

bash 
# tidak-dijalankan (tahap pemasangannya memerlukan koneksi internet)
# mencatat seluruh package lingkungan beserta versi terpasangnya
python3 -m pip freeze > requirements.txt

# memasang kembali seluruh dependensi pada lingkungan yang lain
python3 -m pip install -r requirements.txt

Pola yang lazim adalah menulis requirements.txt berisi batas minimum di awal proyek, lalu menyimpan freeze pada berkas terpisah ketika versi persis perlu direkam. Apa pun polanya, keberadaan berkas dependensi itulah yang membuat kehilangan lingkungan menjadi masalah kecil, karena pembangunan ulang cukup dilakukan dengan satu perintah.

Disiplin isolasi#

Satu proyek dikaitkan dengan satu lingkungan, dan lingkungan itu tidak dipakai bersama proyek lain. Aturan sederhana ini mencegah konflik versi sekaligus membuat daftar dependensi setiap proyek mencerminkan isi lingkungan yang sebenarnya, karena pip freeze hanya menampilkan package yang benar-benar dipakai lingkungan tersebut.

Direktori lingkungan tidak disertakan saat proyek dibagikan, misalnya melalui repository Git. Isinya berjumlah ribuan berkas, sedangkan seluruhnya dapat dibangun ulang dari requirements.txt dalam satu perintah. Berkas .gitignore pada proyek biasanya memuat entri .venv agar lingkungan tertinggal di mesin masing-masing dan tidak ikut tercatat pada riwayat perubahan.

Kesalahan umum#

Package sudah dipasang tetapi impor tetap gagal. Penyebabnya adalah pip yang menjalankan pemasangan berbeda dari interpreter yang menjalankan program, misalnya pip milik Python utama dipakai sementara program dijalankan di dalam lingkungan. Pesannya berupa ModuleNotFoundError, dan pemeriksaannya dilakukan dengan python3 -m pip --version, yang menampilkan jalur site-packages tempat pip itu bekerja. Perbaikannya adalah mengaktifkan lingkungan yang benar terlebih dahulu, lalu mengulang pemasangan dengan python3 -m pip.

Direktori virtual environment dipindahkan atau diganti namanya setelah dibuat. Skrip aktivasi dan interpreter di dalamnya menyimpan jalur asli, sehingga lingkungan yang dipindah sering gagal diaktifkan atau menunjuk lokasi yang sudah tidak ada. Isi lingkungan tidak ada yang perlu dipertahankan, sehingga perbaikan yang benar adalah menghapusnya lalu membuat ulang dengan python3 -m venv di lokasi yang diinginkan, diikuti pip install -r requirements.txt.

Ringkasan#

  • sys.prefix berbeda dari sys.base_prefix pada interpreter yang berjalan di dalam virtual environment, dan perbandingan keduanya menjadi pemeriksaan lingkungan yang mudah.
  • python3 -m venv <direktori> membuat lingkungan berisi interpreter, pip, dan site-packages kosong yang terpisah dari interpreter utama.
  • Aktivasi hanya mengubah PATH terminal yang sedang berjalan, sedangkan pemasangan package selalu menuju lingkungan yang aktif.
  • requirements.txt mencatat dependensi, pip freeze menyalin keadaan lingkungan secara persis, dan keduanya menjadikan lingkungan mudah dibangun ulang.

Referensi#