Python 的 import 徹底解析｜從基礎到應用與錯誤排解的完整指南

By 佐川 直弘 | Naohiro Sagawa (運営者)

※記事内に広告を含みます。Amazonアソシエイトとして適格販売により収入を得ています。

1. 前言

當你開始學習 Python 時，幾乎一定會遇到的語法就是import 語句。
在 Python 中，透過活用標準函式庫、外部函式庫，甚至是自製模組，可以更高效地撰寫程式。而實現這一點的關鍵機制就是 import。

本篇文章將以初學者也能理解的方式，詳細解說「import python」的基本用法、進階技巧，以及常見錯誤與對應解決方法。

2. import python 的基本概念

2.1 什麼是 import？

在 Python 中，import 是一種將外部模組載入到程式中的機制。
Python 提供了眾多實用的標準函式庫，透過 import 語句 呼叫這些函式庫，就能更有效率地開發程式。

例如，若要使用執行數學運算的 math 模組，可以這樣寫：

import math
print(math.sqrt(16))  # 4.0

在上述範例中，我們import 了 math 模組，並使用其中的 sqrt（平方根）函數。

2.2 使用 import 的好處

活用 Python 的 import 有以下幾個優點：

1. 提升程式碼的重複利用性

• 使用現有函式庫，無需從頭撰寫所有功能。

1. 提升開發效率

• 例如，透過 random 模組可以輕鬆產生亂數。
• 範例：
  import random print(random.randint(1, 100)) # 輸出 1 到 100 之間的隨機整數

1. 擴充功能變得更容易

• 導入外部函式庫（如 NumPy 或 Pandas）可以實現更進階的處理功能。

3. Python 中 import 的基本用法

3.1 匯入標準函式庫

Python 提供了許多預先內建的標準函式庫。
例如，math 和 datetime 就是標準函式庫的一部分，可以直接 import 而無需另外安裝。

範例：使用 math 模組

import math
print(math.pi)  # 3.141592653589793
print(math.factorial(5))  # 5! = 120

範例：使用 datetime 模組

import datetime
now = datetime.datetime.now()
print(now)  # 輸出目前的日期與時間

3.2 使用 from … import …

也可以只匯入特定的函式或變數。

範例：只匯入 sqrt 函式

from math import sqrt
print(sqrt(25))  # 5.0

使用這種方式，就可以直接使用 sqrt()，不需寫成 math.sqrt()，讓程式碼更簡潔。

3.3 指定 import 的別名（別稱）

當模組名稱太長時，可以指定別名（alias）來簡化程式碼。

範例：將 numpy 以 np 作為別名匯入

import numpy as np
arr = np.array([1, 2, 3, 4])
print(arr)  # [1 2 3 4]

透過使用別名，可以提升程式碼的可讀性與開發效率。

4. import 的執行順序與內部機制

4.1 模組的搜尋路徑

Python 在 import 模組時，會依照以下順序進行搜尋：

1. 當前目錄
2. 環境變數 PYTHONPATH 所指定的目錄
3. Python 的標準函式庫
4. site-packages 目錄（外部函式庫的安裝位置）

若要確認目前的模組搜尋路徑，可以執行以下程式碼：

import sys
print(sys.path)

輸出結果會是一個列表，顯示 Python 尋找模組時所參考的目錄。

4.2 使用 sys.path.append() 新增路徑

當需要 import 自訂模組時，可以透過手動新增路徑來讓 Python 找到該模組：

import sys
sys.path.append('/path/to/custom/module')
import my_module  # 匯入自訂模組

4.3 __init__.py 的作用

在 Python 中，若某個資料夾內有 __init__.py 檔案，該資料夾就會被視為一個套件（Package）。
這樣就可以 import 該資料夾中的子模組。

5. 總結

• 透過 import 語句，可以有效活用 Python 的標準函式庫與外部函式庫。
• 可以像 import math 一樣匯入標準模組來使用其中的功能。
• 使用 from module import function 可以只匯入特定的函式。
• 利用別名（例如 import numpy as np）可以簡化冗長的模組名稱。
• 理解模組的搜尋路徑，有助於避免 import 錯誤。

在下一篇文章中，我們將介紹 Python import 的進階技巧（例如相對匯入、動態匯入等）。
運用這些知識，將能撰寫更實用、更專業的 Python 程式！🚀

6. import 的進階技巧

Python 的 import 語句不僅能用於基本的匯入操作，也能根據不同情境，靈活運用進階技巧。本章將深入說明 相對匯入、動態匯入，以及萬用字元匯入的風險。

6.1 相對匯入與絕對匯入

在 Python 中，模組的匯入方式主要分為 「絕對匯入」 和 「相對匯入」 兩種。

6.1.1 絕對匯入

絕對匯入 是指從專案根目錄（最上層目錄）開始指定模組的完整路徑。

# 專案結構範例
my_project/
│── main.py
│── utils/
│   ├── helper.py
│   └── math_utils.py

若要在 main.py 中匯入 math_utils.py，可使用以下方式：

# main.py
import utils.math_utils  # 絕對匯入

6.1.2 相對匯入

相對匯入 是透過相對於當前檔案位置的路徑，來匯入模組。

例如，從 helper.py 匯入 math_utils.py 可寫成：

# helper.py
from . import math_utils  # 匯入同一目錄下的模組
from .. import another_module  # 匯入上層目錄的模組

6.2 使用 importlib 進行動態匯入

通常，Python 的 import 語句會在程式執行時只被解析一次。但有時你可能需要根據執行時的情況，動態決定要匯入哪個模組，這時就可以使用 importlib 模組。

6.2.1 使用 importlib.import_module()

例如，你只想在已安裝 numpy 的情況下匯入它，可以這麼寫：

import importlib

module_name = "math"
math_module = importlib.import_module(module_name)

print(math_module.sqrt(25))  # 5.0

6.3 使用 import *（萬用字元匯入）的風險

使用 from module import * 可一次匯入模組中的所有函式與變數：

from math import *
print(sqrt(16))  # 4.0

6.3.1 為什麼要避免使用萬用字元匯入？

⚠ 不容易辨別實際匯入了哪些函式或變數
⚠ 容易發生命名衝突（不同模組可能有同名函式）
⚠ 可能匯入不需要的物件，造成效能下降

建議做法

• 明確指定所需的函式

from math import sqrt, pi

• 使用別名提高可讀性

import numpy as np

7. import 錯誤的原因與對策

在使用 Python 的 import 語句時，初學者常會遇到幾種錯誤。本章將詳細說明 各種常見的 import 錯誤、成因與解決方法。

7.1 ModuleNotFoundError: No module named 'xxx'

錯誤訊息範例：

ModuleNotFoundError: No module named 'numpy'

可能原因：

• 尚未安裝像 numpy 等外部函式庫
• sys.path 中缺少模組所在的目錄
• 使用了錯誤的 Python 虛擬環境

解決方法：

✅ 安裝所需模組

pip install numpy

✅ 檢查目前環境中已安裝的套件

pip list

✅ 啟用虛擬環境（以 venv 為例）

source venv/bin/activate  # 適用於 Mac/Linux
venvScriptsactivate  # 適用於 Windows

✅ 檢查模組搜尋路徑

import sys
print(sys.path)

如果找不到目標模組，可使用 sys.path.append('路徑') 將自訂目錄加入搜尋路徑。

7.2 ImportError: cannot import name 'xxx'

錯誤訊息範例：

ImportError: cannot import name 'my_function' from 'my_module'

可能原因：

• my_module.py 中並未定義 my_function
• import 語句語法錯誤（例如錯誤地匯入類別當成函式）
• 循環匯入（circular import）

解決方法：

✅ 確認目標模組是否正確定義
請檢查 my_module.py 是否正確定義了 my_function。

✅ 修正錯誤的 import 寫法

# 錯誤
from my_module import my_function

# 正確
import my_module
print(my_module.my_function())

✅ 確認是否為循環匯入問題
請參考下方 7.3 小節說明。

7.3 循環匯入（Circular Import）

錯誤訊息範例：

ImportError: cannot import name 'A' from partially initialized module 'B'

可能原因：

• module_a.py 匯入了 module_b.py，而 module_b.py 又反過來匯入了 module_a.py，造成循環

範例：會導致循環匯入錯誤的程式碼：

module_a.py

from module_b import B
class A:
    pass

module_b.py

from module_a import A
class B:
    pass

此時執行 module_a.py，就會發生循環匯入錯誤。

解決方法：

✅ 將 import 移入函式內進行延遲匯入

# module_a.py
def use_module_b():
    from module_b import B
    b_instance = B()

✅ 重新設計模組的相依關係

• 盡量 減少模組之間的相依性
• 避免單一模組承擔多重責任

✅ 使用延遲匯入（Lazy Import）技巧

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from module_b import B

8. 常見問題（FAQ）

針對 Python 中的 import 語句，這裡以 問與答形式，為初學者到中階使用者解答一些常見疑問，並結合實際錯誤訊息與範例，提供對應的解決方式。

8.1 import 和 from ... import ... 有什麼不同？

A：
import 與 from ... import ... 都是匯入模組的方法，但使用方式與結果略有不同。

1. 使用 import

import math
print(math.sqrt(16))  # 4.0

• 這會將整個 math 模組匯入。
• 使用函式時必須加上模組名稱，例如 math.sqrt(16)。

2. 使用 from ... import ...

from math import sqrt
print(sqrt(16))  # 4.0

• 這只會匯入 sqrt() 函式。
• 可以直接使用函式，不需加上模組名稱，讓程式碼更簡潔。

8.2 出現 ModuleNotFoundError: No module named 'xxx' 時怎麼辦？

✅ 確認是否已安裝該模組

pip install numpy

✅ 確認是否已啟用正確的虛擬環境

source venv/bin/activate  # 適用於 Mac/Linux
venvScriptsactivate  # 適用於 Windows

8.3 出現 ImportError: cannot import name 'xxx' 的原因是什麼？

✅ 確認模組內確實有該函式或類別

import my_module
print(dir(my_module))  # 查看 my_module 中可用的物件

✅ 為了避免循環匯入，可將 import 移到函式內部

def use_module_b():
    from module_b import some_class

8.4 可以使用 import * 嗎？

A：
基本上不建議使用。

⚠ 不易判斷實際匯入了哪些函式或變數
⚠ 容易發生命名衝突
⚠ 可能匯入不必要的物件，造成效能浪費

建議做法：

from math import sqrt, pi

8.5 如何重新載入已匯入的模組？

✅ 使用 importlib.reload() 函式

import importlib
import my_module

importlib.reload(my_module)

9. 結語（下一步學習建議）

透過本篇文章，相信你已經理解了 Python 中 import 語句的運作方式，並學會了如何有效地使用模組與函式庫。我們從 基本用法、進階技巧，到常見錯誤的排除方法 都進行了詳細解說。

在 Python 程式設計中，掌握 import 機制是提升程式可讀性與開發效率的重要技巧。請善用這些知識，拓展你的 Python 技能與實務應用能力！

9.1 下一步可以學什麼？

當你已經熟練掌握 import 的基本用法，建議可以繼續學習以下主題：

1. Python 的套件管理工具（pip 與 venv）

在使用 import 語句時，如何安裝與管理外部函式庫非常關鍵。學會使用 pip 來安裝套件，以及建立虛擬環境（venv）可以讓你的開發環境更加穩定與專業。

pip install requests  # 安裝函式庫
python -m venv myenv  # 建立虛擬環境
source myenv/bin/activate  # 啟用虛擬環境（Mac/Linux）
myenvScriptsactivate  # 啟用虛擬環境（Windows）

2. Python 的物件導向設計（類別與方法）

當你開始使用 import 將程式碼模組化後，學習 物件導向程式設計（OOP） 會進一步幫助你組織與擴展程式結構。

class Animal:
    def __init__(self, name):
        self.name = name

    def speak(self):
        return "..."

class Dog(Animal):
    def speak(self):
        return "汪汪"

my_dog = Dog("小黑")
print(my_dog.speak())  # 汪汪

3. Python 的並行處理與多執行緒

若你希望挑戰更進階的開發內容，可以學習 並行處理與多執行緒，特別是在處理大量資料或 I/O 操作時非常實用。

import threading

def print_numbers():
    for i in range(5):
        print(i)

thread = threading.Thread(target=print_numbers)
thread.start()
thread.join()

9.2 總結

• 活用 Python 的 import，可以有效使用標準函式庫與外部套件。
• 理解 import 的運作機制，有助於撰寫模組化、可重用的程式碼。
• 進一步學習套件管理、物件導向、並行處理等主題，將有助於提升你的開發實力。
• 請搭配官方文件與學習資源，實際動手寫程式才是最有效的學習方式。

這就是關於「import python」的完整指南！🎉
善用這些知識，挑戰更高階的 Python 程式設計吧！🚀