Python 3.11: PaddleOCR 穩定環境建置完整教學（含 VS Code / Jupyter）

✅ 適用時間點：2026 年
✅ 作業系統：Windows 10 / 11
✅ Python：3.11
✅ OCR 引擎：PaddleOCR 2.7.x
✅ 目標：穩定、不踩 NumPy 2.x ABI 雷

目錄

1. 為什麼一定要用虛擬環境
2. 建立 Python 虛擬環境（venv）
3. VS Code 切換 Interpreter（關鍵）
4. Jupyter Notebook 使用正確 Interpreter
5. 套件版本地雷總整理（⚠️ 重點）
6. 正確安裝 PaddleOCR（不爆炸版）
7. 四行指令確認環境
8. 第一支 PaddleOCR 程式
9. 常見錯誤與判斷方式
10. 結論與最佳實務

1️⃣ 為什麼一定要用虛擬環境？

結論先講：不用 venv，PaddleOCR 幾乎一定會炸。

原因不是你操作錯，而是：

• NumPy 2.x 破壞 ABI 相容性
• PaddlePaddle 2.6.x 仍使用 NumPy 1.x 編譯
• pip 會「好心」幫你升級到最新，然後炸掉

👉 唯一正解：一個專用 venv

2️⃣ powershell建立 Python 虛擬環境（venv）

假設 Python 已安裝（python --version 能跑）

cd D:\user\Python
python -m venv venv-paddleocr

啟動虛擬環境（PowerShell）：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\venv-paddleocr\Scripts\activate

看到：

✅ 成功

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

這條指令的意思是在當前這個 PowerShell 視窗（進程）中，暫時繞過執行策略的限制，允許執行任何腳本。

詳細分解如下：

Set-ExecutionPolicy: 這是用來設定 PowerShell 執行策略（安全規則）的指令。
-Scope Process: 指定設定的範圍僅限於「目前的執行程序」（Process）。
這意味著這個變更只對你現在開著的這個視窗有效。
一旦你關閉了這個視窗，設定就會失效，不會影響到你電腦整體的安全性設定。
-ExecutionPolicy Bypass: 將策略設定為「Bypass」（繞過）。
在這個模式下，沒有任何限制，也不會出現警告或提示。
所有的腳本（包含從網路下載未簽署的腳本）都可以直接執行。
總結：
這通常用在你需要執行某個腳本（例如安裝某些開發工具或環境），但被系統預設較嚴格的安全設定（如 Restricted）擋住時。這是一個相對安全的做法，因為它只影響當次操作，不會永久降低系統的防護等級。

在 VS Code 中，只要使用「Python: Select Interpreter」或 Notebook Kernel 切換，
實際上並不會執行 activate.ps1，因此也不會受到 PowerShell ExecutionPolicy 限制。
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
僅在「手動於 PowerShell 啟用 venv」時才需要。

3️⃣ VS Code 切換 Python Interpreter（⚠️ 非常重要）

✅ 方法一（推薦）

1. Ctrl + Shift + P
2. 輸入：Python: Select Interpreter
3. 選擇：

...\venv-paddleocr\Scripts\python.exe

✅ 方法二（右下角）

• 點擊右下角 Python 版本
• 切換到 venv-paddleocr

📌 不切 Interpreter = 用錯 Python = 套件裝到別的地方

4️⃣ Jupyter Notebook 使用正確 Interpreter

✅ 在 venv-paddleocr 中安裝 Jupyter

pip install jupyter ipykernel

✅ 把 venv 加入 kernel

python -m ipykernel install --user --name venv-paddleocr --display-name "Python (paddleocr)"

✅ 在 Notebook 右上角選：

✅ 這一步沒做，Notebook 會偷用系統 Python

5️⃣ 套件版本地雷總整理（⚠️ 必看）

6️⃣ 正確安裝 PaddleOCR（不踩雷流程）

✅ Step 1：安裝 NumPy（先）

pip install numpy==1.26.4

✅ Step 2：安裝 PaddlePaddle（CPU）

pip install paddlepaddle==2.6.2

✅ Step 3：安裝 OpenCV（相容版）

pip install opencv-python-headless==4.6.0.66

✅ Step 4：安裝 PaddleOCR

pip install paddleocr==2.7.3

7️⃣ 四行指令確認環境（工程版）

python -c "import numpy; print('numpy', numpy.__version__)"
python -c "import paddle; print('paddle', paddle.__version__)"
python -c "import cv2; print('opencv', cv2.__version__)"
python -c "import paddleocr; print('paddleocr', paddleocr.__version__)"

正確輸出：

numpy 1.26.4
paddle 2.6.2
opencv 4.6.0
paddleocr 2.7.3

✅ 到這裡，環境 已可交付

8️⃣ 第一支 PaddleOCR 程式（英文截圖）

from paddleocr import PaddleOCR

ocr = PaddleOCR(
    lang="en",
    use_angle_cls=True
)

result = ocr.ocr(r"D:\Temp\my_screenshot.png", cls=True)

for line in result[0]:
    text, score = line[1]
    print(f"{text} ({score:.2f})")

第一次執行會下載模型，正常。

9️⃣ 常見錯誤與判斷方式

❌ ABI Error（最常見）

module compiled against ABI version 0x1000009

✅ 解法：NumPy 降級到 1.26.4

⚠️ angle classifier warning

WARNING: angle classifier is not initialized

✅ 圖片全正 → 可忽略
✅ 有旋轉 → 加 use_angle_cls=True

🔟 結論與最佳實務

✅ 核心原則

PaddleOCR = NumPy 1.x 世界
pip 住在 NumPy 2.x 世界

👉 一定要「人為鎖版本」

✅ 建議存一個 requirements.txt

numpy==1.26.4
paddlepaddle==2.6.2
paddleocr==2.7.3
opencv-python-headless==4.6.0.66

✅ 最後一句話

這不是你不會裝，是 Python 生態正在經歷 ABI 轉換期。

推薦hahow線上學習python: https://igrape.net/30afN