Pernahkah import berjalan mulus di satu folder tetapi menolak bekerja di folder lain, dengan pesan ModuleNotFoundError yang tampak tanpa alasan? Di balik import yang terasa ajaib itu ada mekanisme pencarian yang sepenuhnya bisa kita telusuri: daftar lokasi bernama sys.path. Pada Chapter ini kita membongkar daftar tersebut, memahami peran environment variable PYTHONPATH, dan mengenali jebakan klasiknya.

Bagaimana import Mencari Module #

Ketika interpreter menemui import sapa, interpreter mencari module bernama sapa di serangkaian lokasi berurutan. Berhenti di temuan pertama. Urutannya:

  1. Direktori script yang dijalankan — atau direktori saat ini bila kita memakai REPL / python3 -c.
  2. Daftar folder pada environment variable PYTHONPATH (bila diisi).
  3. Lokasi standard library bawaan instalasi Python.
  4. Folder site-packages tempat package pip dipasang.

Daftar lengkap lokasi tersebut tersimpan sebagai list bernama sys.path di dalam module sys — dan urutannya memang segalanya: module di lokasi awal selalu menang.

Memeriksa sys.path #

Kita bisa mencetak isi sys.path kapan saja. Simpan kode berikut sebagai inspeksi_path.py (versi ini sengaja meringkas tiap entri menjadi nama foldernya saja supaya tetap pendek):

python 
import os
import sys

print("Jumlah entri sys.path:", len(sys.path))

for index, path in enumerate(sys.path):
    if path == "":
        print(index, "(direktori saat ini)")
    else:
        print(index, os.path.basename(path))

Jalankan dengan python3 inspeksi_path.py:

Output yang Dihasilkan:

text 
Jumlah entri sys.path: 5
0 project-belajar
1 python312.zip
2 python3.12
3 lib-dynload
4 site-packages

Mari kita baca hasilnya per baris:

  1. Baris 0 project-belajar: entri pertama adalah folder tempat script berada — folder kerja kita sendiri. Inilah alasan file .py di folder yang sama bisa saling import.
  2. Baris 1-3 (python312.zip, python3.12, lib-dynload): lokasi-lokasi standard library tempat module bawaan seperti os dan sys tinggal.
  3. Baris 4 site-packages: rumah bagi package yang dipasang pip.

Nama folder yang tampil di mesin kita sendiri akan mengikuti instalasi Python masing-masing — inti polanya tetap: folder script dulu, standard library kemudian, site-packages terakhir.

Peran PYTHONPATH #

Environment variable PYTHONPATH memungkinkan kita menambahkan folder pencarian sendiri tanpa memindahkan file. Manfaatnya paling terasa lewat contoh. Bayangkan struktur kerja berikut:

text 
project-belajar/
├── program.py
└── utils/
    └── sapa.py

File program.py berisi import sapa, tetapi sapa.py berada di folder utils/ — bukan folder yang sama dengan program.py. Karena entri pertama sys.path adalah folder project-belajar saja, pencarian gagal (Python menampilkan jalur lengkap file di mesin kita; di sini dipendekkan agar mudah dibaca):

text 
Traceback (most recent call last):
  File "/home/budi/project-belajar/program.py", line 1, in <module>
    import sapa
ModuleNotFoundError: No module named 'sapa'

Kini jalankan ulang dengan menambahkan folder utils ke PYTHONPATH:

bash 
$ PYTHONPATH=utils python3 program.py
Halo, Budi! Selamat belajar.

Berhasil. Nilai utils pada PYTHONPATH menyisipkan folder tersebut ke daftar pencarian — berada setelah folder script namun sebelum standard library. Formatnya di terminal Linux/macOS adalah PYTHONPATH=folder1:folder2 python3 program.py (pemisah titik dua); di Windows PowerShell, variabelnya di-set dengan $env:PYTHONPATH="folder1;folder2" (pemisah titik koma) sebelum menjalankan perintah biasa.

Jebakan yang Perlu Dikenali #

Mekanisme pencarian berurutan membawa satu konsekuensi penting: nama module kita bisa mengalahkan standard library. Misalkan kita membuat file json.py di folder kerja untuk latihan. Statement import json pada program di folder yang sama kini memuat file latihan tersebut — bukan module json bawaan — dan program kita tetap tampak sehat sampai baris ketika json.dumps() ternyata tidak ada di file kita. Gejala klasiknya: error aneh di kode yang “tadi masih jalan”.

Dengan memahami cara Python menemukan module, satu kategori masalah besar kini berada dalam kendali kita. Chapter penutup section ini merangkum kunci pengurai masalah untuk situasi yang paling sering menghantui pemula: instalasi yang tidak terdeteksi, versi yang bertukar, dan PATH yang bermasalah.