為什麼同一個 main.py,用 python pkg/main.py 執行會丟出 ImportError: attempted relative import with no known parent package,換成 python -m pkg.main 卻能正常跑完?檔案裡寫了 from . import helper 之類的相對匯入,再照原本的習慣直接執行檔案,就常常會碰到這個錯誤。

重現用的例子:demo 資料夾底下只有一個 pkg 套件,裡面放 __init__.py(空檔案)、helper.py 和 main.py:

# pkg/helper.py
def greet():
    return "hello from helper"

# pkg/main.py
print("__name__ =", repr(__name__))
print("__package__ =", repr(__package__))

from . import helper

print(helper.greet())

兩次輸出

在 demo 這一層,兩種方式各執行一次(Python 3.14):

$ python pkg/main.py
__name__ = '__main__'
__package__ = None
Traceback (most recent call last):
  File ".../demo/pkg/main.py", line 4, in <module>
    from . import helper
ImportError: attempted relative import with no known parent package

$ python -m pkg.main
__name__ = '__main__'
__package__ = 'pkg'
hello from helper

第一行都是 __name__ = '__main__'。這裡就有個意外,用了 -m,模組名稱也沒有變成 pkg.main,main.py 一樣是主模組,所以檔案底下如果有 if __name__ == "__main__":,兩種執行方式都會進去。

不同的地方在第二行:直接執行時 __package__ 是 None,用 -m 執行時是 'pkg'。Python 3.6 以後,匯入時會先看 __spec__.parent,沒有才退回 __package__;用 -m 執行時兩者都是 'pkg')。from . import helper 的 . 指的是目前所在的套件。直接執行時 __package__ 是 None,Python 不知道 . 是哪一個套件,錯誤訊息裡的 no known parent package 這段的來源。

那 -m 怎麼知道套件是 pkg?-m 會先透過一般的匯入機制把模組找出來,再當成 __main__ 模組執行(命令列的說明)。指令裡的 pkg.main 本來就是模組名稱,從輸出可以看到,名稱前面 pkg 就成了 __package__。直接給檔案路徑時,pkg/main.py 只是一個要執行的檔案,雖然旁邊有 __init__.py,__package__ 還是 None。

另外,-m 會把目前所在的資料夾加到 sys.path 開頭,所以要在 pkg 的上一層(demo)執行(這一步很容易漏掉,先 cd 進 pkg 再下 python -m pkg.main,會看到 No module named 'pkg')。

改執行指令,或是改匯入

假設平常都是在 demo 層開終端機,程式其實一行都不用動,把指令換成 python -m pkg.main 就可以了。

Python 教學的模組章節則是建議另一條路:主模組沒有套件,所以要當主模組執行的模組,一律用絕對匯入。等等,剛剛用 -m 跑的 main.py 明明也是主模組,相對匯入卻沒有出錯?主模組沒有套件,比較貼近直接用檔名執行的情況,那時 __package__ 確實是 None。用 -m 就不一樣了,__package__ 當初加進來,本來就是為了讓 -m 執行的模組能直接用相對匯入。所以教學的說法偏保守,不代表 -m 底下的相對匯入有問題。

不過改成絕對匯入,也不是把 main.py 裡那一行換掉就能直接執行。from . import helper 改成 from pkg import helper,再執行 python pkg/main.py,錯誤會變成 ModuleNotFoundError: No module named 'pkg'。而直接執行檔案時,Python 會把檔案所在的資料夾加到 sys.path 開頭,也就是 pkg 本身,而不是上一層的 demo,所以找不到 pkg。

入口檔案改放在 demo 這一層,pkg 就找得到了,比如另外放一個 run.py:

# run.py
from pkg import main
$ python run.py
__name__ = 'pkg.main'
__package__ = 'pkg'
hello from helper

這次發現 __name__ 變成 'pkg.main' 了。主模組換成 run.py,它用絕對匯入載入 pkg.main,pkg/main.py 變成只是被匯入的模組,裡面的 from . import helper 照樣能用。

碰到這個錯誤,我覺得最容易誤會的地方,是它看起來很像 import 寫錯了,但前面兩次執行,發現變的只有執行的方式。