Python 模組與套件教學 — import 用法與 __main_

Python 模組與套件（Modules and Packages）

這篇 Python import 教學將帶你認識模組（module）與套件（package）：當程式越寫越大，不可能全部塞在一個檔案，模組就是「一個 .py 檔」，套件是「一個裝著多個模組的資料夾」。猜數字遊戲用過的 import random，現在來搞懂它。

import 的各種寫法

寫法	用法	呼叫方式
`import random`	匯入整個模組	`random.randint(1, 10)`
`import random as rd`	取別名	`rd.randint(1, 10)`
`from random import randint`	只匯入需要的名稱	`randint(1, 10)`
`from random import *`	全部倒進來（不建議）	`randint(1, 10)`

import random
from math import sqrt, pi

print(random.randint(1, 6))   # 擲骰子（你的結果可能不同）
print(sqrt(16))
print(pi)

執行輸出：

4
4.0
3.141592653589793

from x import * 不建議：分不清名稱從哪來，還可能蓋掉既有的變數。

常用的內建模組

Python「內建電池」非常豐富，這些之後的文章都會用到：

模組	用途
`random`	隨機數
`math`	數學運算
`datetime`	日期時間（第 34 篇）
`json`	JSON 處理（第 33 篇）
`os`、`pathlib`	檔案與路徑
`re`	正規表達式（第 35 篇）

建立自己的模組

模組就是一個 .py 檔。假設有個 mytools.py：

# mytools.py
def add(a, b):
    return a + b

PI = 3.14159

同資料夾的另一個檔案就能匯入使用：

# main.py
import mytools

print(mytools.add(3, 5))
print(mytools.PI)

執行輸出：

8
3.14159

套件則是裝著模組的資料夾，用 from 資料夾.檔名 import 名稱 一路點進去。

if name == “main” 是什麼

模組被匯入時，整個檔案會被執行一次。如果 mytools.py 裡有測試用的 print，別人 import 它時也會跑出來。解法是入口判斷：

# mytools.py
def add(a, b):
    return a + b

if __name__ == "__main__":
    # 只有「直接執行這個檔案」才會跑，被 import 不會
    print("測試：", add(3, 5))

原理：直接執行時 __name__ 是 "__main__"；被 import 時是模組名 "mytools"。這行慣例幾乎每個正式的 Python 檔案都有。

常見錯誤

1. ModuleNotFoundError: No module named ‘xxx’

三種可能：（1）名稱打錯；（2）第三方套件還沒安裝（下一篇 uv 會教 uv add）；（3）自訂模組不在執行目錄。先確認檔案位置與名稱拼字。

2. 檔名跟模組撞名

把檔案取名 random.py 再 import random，會匯入你自己的檔案，報出莫名其妙的 AttributeError。自己的檔名避開內建模組名。

3. ImportError: cannot import name ‘xxx’

from mytools import addd 名稱拼錯，或該模組裡根本沒有這個名稱。用 dir(mytools) 可以列出模組裡所有名稱。

總結

模組＝.py 檔、套件＝資料夾；import x 全拿、from x import y 只拿需要的、避免 import *；每個正式檔案都該有 if __name__ == "__main__": 入口。撞名與拼錯是 ModuleNotFoundError 的最大宗。下一篇學會用 uv 管理虛擬環境與第三方套件。

延伸閱讀

ㄚ槌