Jika file Python di dalam paket memunculkan ImportError: attempted relative import with no known parent package saat Anda menjalankannya secara langsung, mulailah sebagai modul dari direktori di atas paket tersebut. Di macOS, berpindahlah ke root proyek di Terminal, lalu jalankan python3 -m package.module. Ini memberi Python konteks paket yang tidak disediakan oleh path file langsung.

Mengapa relative import gagal saat saya menjalankan file secara langsung?

Relative import seperti from .helpers import format_result bergantung pada nama paket modul tersebut. Python menggunakan titik di awal untuk mengidentifikasi paket saat ini dan induknya. Saat Anda menjalankan file dengan python3 path/to/file.py, Python menjalankan file tersebut sebagai modul __main__ tingkat teratas; Python tidak memberinya metadata paket yang diperlukan untuk mengatasi (resolve) titik tersebut. Oleh karena itu, proses impor dapat gagal meskipun helpers.py berada di samping file tersebut. Referensi impor Python menjelaskan relative import dan penanganan khusus untuk __main__.

Sebagai contoh, misalkan proyek Anda diatur seperti ini:

project/
└── myapp/
    ├── __init__.py
    ├── cli.py
    └── helpers.py

Jika cli.py berisi from .helpers import format_result, menjalankan python3 myapp/cli.py dari project adalah pemanggilan yang salah. Masalahnya terletak pada bagaimana Python diminta untuk menjalankan file tersebut, belum tentu karena relative import atau lokasi file-nya yang salah.

Jalankan modul dari root proyek di macOS

Buka Terminal dan berpindahlah ke direktori yang berisi myapp. Ganti path contoh dengan lokasi proyek Anda yang sebenarnya. Beri tanda kutip pada path agar spasi ditangani oleh shell; shell default Terminal macOS adalah zsh. Panduan Terminal Apple mendokumentasikan default tersebut.

cd "/Users/yourname/Projects/project"
python3 -m myapp.cli

Opsi -m meminta Python untuk menemukan dan menjalankan modul berdasarkan nama paket berformat titik (dotted package name). Pertahankan nama paket dalam perintah dan hilangkan .py serta garis miring sistem file. Path pencarian modul Python dimulai dengan direktori saat ini ketika dipanggil dengan -m, itulah mengapa menjalankan dari root proyek menjadi penting. Dokumentasi sys.path Python menjelaskan path awal ini.

Jika perintah menggunakan instalasi Python yang salah, aktifkan virtual environment proyek yang sudah ada terlebih dahulu, lalu gunakan pola python -m yang sama. Untuk .venv standar di root proyek:

cd "/Users/yourname/Projects/project"
source .venv/bin/activate
python -m myapp.cli

Menggunakan python setelah aktivasi akan memilih interpreter milik environment tersebut. Jika environment Anda memiliki nama atau lokasi yang berbeda, sesuaikan path aktivasinya; jangan berasumsi .venv pasti ada. Anda dapat memeriksa interpreter yang dipilih dengan python -c 'import sys; print(sys.executable)'.

Jika Anda ingin menjalankan paket itu sendiri

Untuk perintah yang dimaksudkan untuk meluncurkan paket, tambahkan __main__.py di dalam paket dan buat entry point tetap ringkas:

myapp/
├── __init__.py
├── __main__.py
├── cli.py
└── helpers.py

Di dalam myapp/__main__.py, impor dan panggil fungsi utama (entry function) milik paket. Kemudian jalankan python3 -m myapp dari root proyek. Python mengeksekusi __main__.py milik paket untuk bentuk pemanggilan -m ini, dan file tersebut dapat menggunakan import yang relatif terhadap paket. Dokumentasi __main__ Python menjelaskan pola package entry-point ini.

Periksa detail ini jika kesalahan masih berlanjut

  • Konfirmasikan direktori kerja Anda. Jalankan pwd di Terminal dan pastikan perintah tersebut mencetak root proyek, yaitu direktori yang berisi myapp. Jika paket berada di dalam src, misalnya, gunakan nama paket yang dapat diimpor dan pastikan environment proyek yang dikonfigurasi menyediakannya; hanya berpindah ke folder induk yang salah tidak akan memperbaiki penemuan modul.
  • Gunakan nama paket yang sebenarnya. Pada python3 -m myapp.cli, myapp harus merupakan nama direktori paket (atau nama impornya), dan cli adalah nama file modul tanpa ekstensi .py.
  • Periksa baris traceback. Jika relative import berhasil diselesaikan tetapi impor berikutnya gagal, itu mungkin karena modul atau dependensi lain yang hilang. Memperbaiki konteks peluncuran hanya mengatasi kegagalan terkait konteks paket.
  • Hindari PYTHONPATH sebagai solusi pertama. Opsi ini mengubah path pencarian impor Python, tetapi tidak secara otomatis mengubah file yang dieksekusi secara langsung menjadi modul paket yang dinamai dengan benar. Python juga memperingatkan bahwa PYTHONPATH dapat memengaruhi beberapa versi dan environment Python sekaligus. Referensi inisialisasi path Python menjelaskan cakupannya.
  • Jika eksekusi file langsung adalah sebuah keharusan, pertimbangkan untuk mengubah kode agar menggunakan absolute import yang sesuai dan pastikan paket terinstal atau dapat diimpor di environment tersebut. Itu adalah pilihan konfigurasi yang berbeda; jangan mencampur relative import paket dengan ekspektasi bahwa file tersebut berperilaku seperti skrip mandiri.

Aturan praktisnya adalah mencocokkan perintah dengan gaya impor: untuk relative import paket, jalankan modul dari direktori induk paket dengan python -m. Untuk perintah paket, sediakan __main__.py dan jalankan paket dengan -m.

Sumber