Python Virtual Environment

Cheat sheet lengkap untuk setup dan manajemen Python virtual environment.

️ Masalah: Kenapa Butuh Virtual Environment?

Global Package Conflict

Bayangkan dua project Python di server yang sama:

• Project A butuh Django 3.2
• Project B butuh Django 5.0

Jika di-install global, terjadi konflik - hanya satu versi yang bisa aktif.

PEP 668 - Perlindungan Sistem

Mulai Python 3.11+, banyak distro (termasuk Ubuntu 24.04+) menerapkan PEP 668: pip dilarang menginstal package ke sistem Python secara global.

error: externally-managed-environment
× This environment is externally managed
╰─> To install Python packages system-wide, try apt install python3-xyz,
    where xyz is the package you are trying to install.

Solusi: Selalu gunakan virtual environment.

Solusi: Virtual Environment

Cara Bawaan: venv (stdlib - tanpa install)

# Buat virtual environment
python3 -m venv .venv

# Aktivasi (Linux/Mac)
source .venv/bin/activate

# Aktivasi (Windows CMD)
.venv\Scripts\activate.bat

# Aktivasi (Windows PowerShell)
.venv\Scripts\Activate.ps1

# Cek lokasi Python
which python
# Output: /home/user/project/.venv/bin/python

# Deaktivasi
deactivate

Struktur Folder .venv/

.venv/
├── bin/           # Python, pip, skrip aktivasi
│   ├── activate
│   ├── python
│   └── pip
├── lib/           # Installed packages
│   └── python3.11/
│       └── site-packages/
├── pyvenv.cfg     # Konfigurasi venv
└── include/       # Header C (untuk build)

uv - Super Cepat (Rekomendasi)

uv adalah manajemen Python modern yang sangat cepat (ditulis dalam Rust).

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Atau via pip:

pip install uv

Penggunaan uv

# Buat virtual environment otomatis
uv venv

# Install packages (super cepat)
uv pip install flask requests

# Sync dari requirements.txt
uv pip sync requirements.txt

# Install requirements
uv pip install -r requirements.txt

# Run command dalam venv tanpa aktivasi
uv run python script.py
uv run flask run

# Lihat dependency tree
uv pip tree

Perbandingan kecepatan: uv bisa 10-100x lebih cepat dari pip karena tidak perlu memproses metadata satu per satu.

pip & requirements.txt

# Setelah aktivasi, install package
pip install flask==3.0.0 requests pandas

# Simpan daftar dependency
pip freeze > requirements.txt

# Install dari file
pip install -r requirements.txt

# Upgrade semua package
pip list --outdated
pip install --upgrade <package>

Contoh requirements.txt

flask==3.0.0
requests==2.31.0
pandas>=2.0.0,<3.0.0
numpy>=1.24.0
gunicorn==21.2.0

Dev vs Production Dependencies

# requirements.txt - production
# requirements-dev.txt - development (extends production)

requirements-dev.txt:

-r requirements.txt
pytest==7.4.0
black==23.12.0
ruff==0.1.0
pylint==3.0.0

.gitignore untuk venv/

Jangan pernah commit folder .venv/ ke Git! Tambahkan ke .gitignore:

# Virtual environment
.venv/
venv/
.venv.*/
ENV/
env/

# Python cache
__pycache__/
*.pyc
*.pyo
*.pyd

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

Multi-Version Python dengan pyenv

pyenv memungkinkan Anda menggunakan berbagai versi Python di satu mesin.

Install pyenv

curl https://pyenv.run | bash

Penggunaan pyenv

# Lihat versi yang tersedia
pyenv install --list

# Install versi tertentu
pyenv install 3.12.0
pyenv install 3.11.7
pyenv install 3.10.13

# Set global (default)
pyenv global 3.12.0

# Set per-project
cd /home/project
pyenv local 3.11.7   # buat file .python-version

# Lihat versi aktif
pyenv versions

Kombinasi pyenv + venv

# Set Python version dulu
pyenv local 3.11.7

# Buat venv dengan Python version itu
python3 -m venv .venv

# Aktivasi
source .venv/bin/activate

# Cek versi
python --version
# Output: Python 3.11.7

Auto-Activation dengan direnv

direnv otomatis mengaktifkan venv saat cd ke folder project.

Install direnv

sudo apt install direnv
# Tambahkan ke shell rc
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

Konfigurasi

Buat file .envrc di root project:

layout python3
# atau custom path
source .venv/bin/activate

# Allow pertama kali
direnv allow

Sekarang setiap cd ke folder project, venv otomatis aktif. Saat cd keluar, otomatis deactivate.

Best Practices

1. Selalu Gunakan Venv

# WAJIB setiap project baru
python3 -m venv .venv
source .venv/bin/activate

2. Lock File - Reproducible Builds

Gunakan pip freeze atau uv pip freeze untuk lock semua dependency beserta versinya:

pip freeze > requirements.lock.txt
# atau dengan uv
uv pip freeze > requirements.lock.txt

3. Dev Dependencies Terpisah

# requirements.txt - untuk production
flask==3.0.0
gunicorn==21.2.0

# requirements-dev.txt - untuk development
-r requirements.txt
pytest==7.4.0
black==23.12.0

4. Jangan Pakai sudo pip

# ❌ SALAH - merusak system Python
sudo pip install flask

# ✅ BENAR
python3 -m venv .venv
source .venv/bin/activate
pip install flask

5. Gunakan .venv Nama Folder

Konsisten dengan nama .venv - sudah standar industri, otomatis di-ignore banyak tools.

6. Upgrade pip di Venv

pip install --upgrade pip

Troubleshooting

command not found: pip

Setelah aktivasi venv, pip harusnya tersedia. Jika tidak:

# Install pip di venv
python3 -m ensurepip --upgrade

# Atau install manual
python3 -m pip install --upgrade pip

permission denied saat install

Jangan pakai sudo di dalam venv! Jika dapat error permission, berarti venv rusak. Buat ulang:

rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate

Shebang Python

File script dengan shebang #!/usr/bin/env python akan menggunakan Python dari venv jika dijalankan setelah aktivasi.

Agar script tetap pakai venv meski tanpa aktivasi:

#!/usr/bin/env python
# atau untuk spesifik
#!/home/project/.venv/bin/python

PATH Issues

Jika which python masih指向 system Python setelah aktivasi:

# Cek apakah venv di PATH
echo $PATH | grep .venv

# Re-activate
deactivate
source .venv/bin/activate

Ringkasan Perintah

💡 Golden Rule: Setiap project Python = satu virtual environment. Jangan pernah install package global di sistem - gunakan venv atau uv!