此mssql-django套件是 Microsoft 官方支援的 Django 資料庫後端，支援 SQL Server、Azure SQL Database、Azure SQL 受控執行個體 及 Microsoft Fabric 中的 SQL 資料庫。 本文說明如何安裝套件及其相依性。
先決條件
- Python 3.8 或更高版本。 Django 6.0 需要 Python 3.12 及更新版本。
- PIP 套件管理器（隨 Python 3.4 及更新版本附贈）
- 適用於 SQL Server 的 Microsoft ODBC 驅動程式 17 或 18。 請參閱下載 SQL Server 的 ODBC 驅動程式。
Important
與 mssql-python 驅動程式不同，mssql-django 需要外部 ODBC 驅動程式。 在設定你的 Django 專案之前，先安裝 Microsoft ODBC 的 SQL Server 驅動程式。
從 PyPI 安裝
用 PIP 安裝套件。 此指令同時自動安裝 Django、pyodbc 和 pytz：
pip install mssql-django
要升級現有設施：
pip install --upgrade mssql-django
若要安裝特定版本：
pip install mssql-django==1.7.3
相依性與版本相容性
在 1.7.3 版本 mssql-django 中，套件的元資料包含以下相依性限制：
| 組件 | 版本指引 |
|---|---|
| Python | 3.8 或更新版本 |
| Django |
>=3.2 與 <6.1 |
| pyodbc | >=3.0 |
| pytz | 安裝為依賴 |
Tip
除非你有經過驗證的鎖定檔，否則讓 pip 解析出相容的版本。 釘選舊 pyodbc 版本即使安裝成功，仍可能導致執行時問題。
確認安裝情況
安裝後，請確認套件安裝正確：
pip show mssql-django
預期產出：
Name: mssql-django
Version: 1.7.3
Summary: Django backend for Microsoft SQL Server
透過測試 ODBC 層來驗證 Python 的安裝：
import pyodbc
print(f"pyodbc version: {pyodbc.version}")
print(f"Available ODBC drivers: {pyodbc.drivers()}")
Note
mssql-django後端會自動在 Django 的資料庫路由系統中設定。 不要直接在應用程式碼中匯入它。 請改為在你的 DATABASES 設定中，將 ENGINE 設為 mssql。
使用虛擬環境
使用 Python 虛擬環境來隔離專案相依性：
python -m venv .venv
啟動虛擬環境：
.venv\Scripts\activate
然後在虛擬環境中安裝 mssql-django ：
pip install mssql-django
平臺特定注意事項
ODBC 驅動程式的安裝步驟會因作業系統而異。
Windows 作業系統
使用從 Download ODBC Driver for SQL Server 下載的 .msi 安裝程式來安裝 Microsoft ODBC Driver 18 for SQL Server。
Linux
請使用你發行版的套件管理器安裝 ODBC 驅動程式。 請參閱 Install the Microsoft ODBC driver for SQL Server （Linux） 以了解平台專屬的說明。
macOS
使用 Homebrew 安裝 ODBC 驅動程式：
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18
依賴
該 mssql-django 套件會自動安裝以下相依性：
| Package | Purpose |
|---|---|
Django |
Web 架構 |
pyodbc |
Python 的 ODBC 資料庫驅動程式 |
pytz |
時區支援 |
pytz 仍依賴套件相容性，但大多數現代 Django 時區工作流程會搭配 USE_TZ=True Django 內建的時區處理。