Python 環境安裝與設定 | Django 教學

2026/05/22 2026/05/21
python django
Python 環境安裝與設定 | Django 教學

在開始學習 Django 之前，第一步是建立一個穩定且正確的 Python 開發環境。本篇教學將手把手帶你在 Windows 、 macOS 與 Linux 三大平台安裝 Python 3.10+ ，並介紹 pip 套件管理器、 venv 虛擬環境的使用方式，以及 VS Code 編輯器的推薦設定，為後續的 Django 開發之旅打下堅實基礎。

為什麼選擇 Python 3.10 以上版本

Django 5.x 的最低要求是 Python 3.10，而截至 2026 年，Python 最新穩定版本為 3.12+。選擇 3.10 以上版本有幾個重要原因：

  • Django 相容性：Django 5.0 起要求 Python 3.10+，使用較舊版本將無法安裝最新的 Django
  • 結構化模式比對（Structural Pattern Matching）：Python 3.10 引入的 match-case 語句讓程式碼更簡潔易讀
  • 更好的型別提示（Type Hints）：Python 3.10+ 支援 X | Y 聯合型別語法，取代冗長的 Union[X, Y]
  • 效能改進：每個新版本都帶來顯著的效能提升

建議直接安裝目前最新的穩定版 Python 3.12 ，以獲得最佳的開發體驗。

Windows 安裝 Python

步驟一：下載安裝檔

前往 Python 官方網站 https://www.python.org/downloads/，點擊「Download Python 3.12.x」按鈕下載 Windows 安裝檔（.exe）。

步驟二：執行安裝程式

重要：安裝時務必勾選底部的「Add python.exe to PATH」選項。 這個步驟會將 Python 加入系統環境變數（Environment Variable），讓你可以在命令提示字元（Command Prompt）或 PowerShell 中直接使用 python 指令。

勾選後，點擊「Install Now」即可使用預設設定安裝。如果你需要自訂安裝路徑，可以選擇「Customize installation」。

步驟三：驗證安裝

安裝完成後，開啟命令提示字元（按 Win + R，輸入 cmd，按 Enter），執行以下指令：

# 檢查 Python 版本
python --version
# 輸出範例：Python 3.12.7

# 檢查 pip 版本
pip --version
# 輸出範例：pip 24.3.1 from C:\Users\...\pip (python 3.12)

如果兩個指令都正確顯示版本號，代表 Python 已成功安裝。

常見問題排除

如果出現「‘python’ 不是內部或外部命令」的錯誤，代表 PATH 未正確設定。你可以：

  1. 重新執行安裝程式，選擇「Modify」並確認勾選「Add Python to environment variables」
  2. 或手動在系統環境變數中加入 Python 的安裝路徑（通常是 C:\Users\你的使用者名稱\AppData\Local\Programs\Python\Python312\）

macOS 安裝 Python

macOS 建議使用 Homebrew 套件管理器來安裝 Python，這是 macOS 開發者最常用的方式。

步驟一：安裝 Homebrew

如果你還沒有安裝 Homebrew，開啟終端機（Terminal），執行以下指令：

# 安裝 Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安裝完成後，依照終端機提示將 Homebrew 加入 PATH（通常需要執行兩行 eval 指令）。驗證安裝：

# 檢查 Homebrew 是否安裝成功
brew --version
# 輸出範例：Homebrew 4.4.x

步驟二：使用 Homebrew 安裝 Python

# 更新 Homebrew 套件清單
brew update

# 安裝最新版 Python
brew install python@3.12

步驟三：驗證安裝

# 檢查 Python 版本
python3 --version
# 輸出範例：Python 3.12.7

# 檢查 pip 版本
pip3 --version
# 輸出範例：pip 24.3.1 from /opt/homebrew/lib/python3.12/site-packages/pip (python 3.12)

注意： 在 macOS 上，Python 3 的指令預設為 python3 和 pip3。如果你希望直接使用 python 指令，可以在 Shell 設定檔（如 ~/.zshrc）中加入別名（Alias）：

# 在 ~/.zshrc 中加入以下內容
alias python='python3'
alias pip='pip3'

# 重新載入設定
source ~/.zshrc

Linux 安裝 Python

大多數 Linux 發行版（Distribution）已預裝 Python，但版本可能較舊。以下分別介紹 Ubuntu/Debian 與 Fedora/RHEL 的安裝方式。

Ubuntu / Debian 系列（使用 apt）

# 更新套件清單
sudo apt update

# 安裝 Python 3.12 與相關工具
sudo apt install python3.12 python3.12-venv python3-pip -y

# 驗證安裝
python3.12 --version
# 輸出範例：Python 3.12.7

pip3 --version
# 輸出範例：pip 24.x.x from /usr/lib/python3/dist-packages/pip (python 3.12)

如果預設的套件庫（Repository）中沒有 Python 3.12，需要先加入 deadsnakes PPA：

# 加入 deadsnakes PPA
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt update

# 安裝 Python 3.12
sudo apt install python3.12 python3.12-venv python3.12-dev -y

Fedora / RHEL 系列（使用 dnf）

# 安裝 Python 3.12
sudo dnf install python3.12 python3.12-pip -y

# 驗證安裝
python3.12 --version
# 輸出範例：Python 3.12.7

pip3 --version
# 輸出範例：pip 24.x.x from /usr/lib/python3.12/site-packages/pip (python 3.12)

設定預設 Python 版本（選用）

如果系統中有多個 Python 版本，可以使用 update-alternatives 來管理預設版本：

# 註冊 Python 版本（Ubuntu/Debian）
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1

# 選擇預設版本
sudo update-alternatives --config python3

pip 套件管理器介紹與使用

pip 是 Python 的標準套件管理器（Package Manager），類似 JavaScript 的 npm 或 Rust 的 cargo。它可以從 PyPI（Python Package Index，Python 套件索引）上下載並安裝第三方套件。

基本指令

# 安裝套件
pip install django
# 輸出範例：Successfully installed django-5.1.x

# 安裝指定版本的套件
pip install django==5.1.4

# 升級已安裝的套件
pip install --upgrade django

# 查看已安裝的套件清單
pip list

# 查看特定套件的詳細資訊
pip show django

# 移除套件
pip uninstall django

# 將目前環境的套件清單輸出到 requirements.txt
pip freeze > requirements.txt

# 從 requirements.txt 批次安裝套件
pip install -r requirements.txt

升級 pip 本身

pip 會不定期更新，建議保持最新版本：

# 升級 pip
python -m pip install --upgrade pip

最佳實踐： 建議使用 python -m pip 而非直接使用 pip 指令，這樣可以確保 pip 對應的是正確的 Python 版本，避免在多版本共存的環境中產生混淆。

虛擬環境（venv）建立與啟用

venv 是 Python 內建的虛擬環境（Virtual Environment）模組，它可以為每個專案建立獨立的套件安裝空間。這是 Python 開發中非常重要的最佳實踐。

為什麼需要虛擬環境

假設你有兩個專案：

  • 專案 A 使用 Django 4.2
  • 專案 B 使用 Django 5.1

如果所有套件都安裝在系統全域（Global）環境中，兩個版本會互相衝突。虛擬環境讓每個專案擁有自己獨立的套件目錄，徹底解決版本衝突問題。

建立虛擬環境

# 建立一個新的專案資料夾
mkdir my-django-project
cd my-django-project

# 建立虛擬環境（慣例命名為 .venv 或 venv）
python -m venv .venv

執行後，會在專案目錄下產生一個 .venv 資料夾，裡面包含獨立的 Python 直譯器（Interpreter）和套件目錄。

啟用虛擬環境

啟用方式依作業系統而不同：

# Windows（命令提示字元）
.venv\Scripts\activate

# Windows（PowerShell）
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

啟用成功後，終端機的提示符號（Prompt）前方會出現 (.venv) 字樣，表示你已進入虛擬環境：

# 啟用前
$ python --version

# 啟用後（注意前方的 (.venv)）
(.venv) $ python --version

在虛擬環境中安裝套件

啟用虛擬環境後，透過 pip 安裝的套件只會存在於該虛擬環境中，不會影響系統全域環境：

# 確認虛擬環境已啟用（提示符號前有 (.venv)）
(.venv) $ pip install django

# 確認 Django 安裝成功
(.venv) $ python -m django --version
# 輸出範例：5.1.4

停用虛擬環境

完成工作後，可以輸入以下指令離開虛擬環境：

# 停用虛擬環境
deactivate

.gitignore 設定

虛擬環境資料夾不應該提交到版本控制系統（Version Control System）。確保你的 .gitignore 檔案中包含以下內容：

# 虛擬環境
.venv/
venv/

VS Code 推薦設定

Visual Studio Code（簡稱 VS Code）是目前最受歡迎的程式碼編輯器之一，對 Python 和 Django 開發有極佳的支援。

必裝擴充套件（Extensions）

  1. Python（Microsoft 官方）：提供語法高亮（Syntax Highlighting）、自動補全（IntelliSense）、程式碼除錯（Debugging）等核心功能
  2. Pylance（Microsoft 官方）：Python 語言伺服器（Language Server），提供更快速的型別檢查和程式碼分析
  3. Django（Baptiste Darthenay）：Django 模板語法高亮與程式碼片段（Snippets）

工作區設定

在專案根目錄建立 .vscode/settings.json，加入以下推薦設定：

{
  // 指定 Python 直譯器路徑（使用虛擬環境）
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",

  // 啟用型別檢查
  "python.analysis.typeCheckingMode": "basic",

  // 儲存時自動格式化
  "editor.formatOnSave": true,

  // 使用 Black 作為格式化工具
  "python.formatting.provider": "black",

  // 終端機自動啟用虛擬環境
  "python.terminal.activateEnvironment": true
}

選擇 Python 直譯器

在 VS Code 中按下 Ctrl + Shift + P（macOS 為 Cmd + Shift + P），輸入「Python: Select Interpreter」，選擇虛擬環境中的 Python 直譯器（路徑中包含 .venv）。這樣 VS Code 就會使用虛擬環境來執行和除錯你的程式碼。

驗證安裝成功

完成以上所有步驟後，讓我們做一個完整的驗證，確認開發環境已正確建立：

# 1. 檢查 Python 版本
python --version
# 預期輸出：Python 3.12.x（3.10 以上即可）

# 2. 檢查 pip 版本
pip --version
# 預期輸出：pip 24.x.x from ... (python 3.12)

# 3. 建立並啟用虛擬環境
mkdir django-test && cd django-test
python -m venv .venv
source .venv/bin/activate  # Windows 使用 .venv\Scripts\activate

# 4. 在虛擬環境中安裝 Django
(.venv) $ pip install django

# 5. 驗證 Django 安裝
(.venv) $ python -m django --version
# 預期輸出：5.1.x

# 6. 快速測試 Django 是否正常運作
(.venv) $ django-admin startproject testproject
(.venv) $ cd testproject
(.venv) $ python manage.py runserver
# 預期輸出：Starting development server at http://127.0.0.1:8000/
# 在瀏覽器開啟 http://127.0.0.1:8000/ 應該看到 Django 歡迎頁面

# 7. 按 Ctrl + C 停止伺服器，清理測試專案
(.venv) $ cd ..
(.venv) $ rm -rf testproject

# 8. 停用虛擬環境
(.venv) $ deactivate

如果以上步驟都順利完成，恭喜你，Python 開發環境已經準備就緒，可以正式開始 Django 的學習之旅了。

總結

本篇教學涵蓋了 Django 開發所需的 Python 環境建置全流程：

  • 版本選擇：建議安裝 Python 3.10+（推薦 3.12），以確保與 Django 5.x 相容
  • 跨平台安裝：Windows 使用官方安裝檔（記得勾選 Add to PATH）、macOS 使用 Homebrew、Linux 使用系統套件管理器（apt 或 dnf）
  • pip 套件管理器：掌握 install、list、freeze、uninstall 等核心指令
  • venv 虛擬環境：為每個專案建立獨立的套件空間，避免版本衝突
  • VS Code 設定：安裝 Python 與 Django 相關擴充套件，配置直譯器路徑與格式化工具

環境建置是開發的第一步，也是最容易被忽略的一步。一個正確設定的開發環境能讓你在後續的學習過程中少走很多彎路。下一篇我們將正式進入 Django 的世界，建立你的第一個 Django 專案。

BenZ Software Developer

熱愛技術的軟體開發者，在這裡分享程式開發經驗與學習筆記。