安裝 mssql-django

此mssql-django套件是 Microsoft 官方支援的 Django 資料庫後端，支援 SQL Server、Azure SQL Database、Azure SQL 受控執行個體 及 Microsoft Fabric 中的 SQL 資料庫。 本文說明如何安裝套件及其相依性。

先決條件

• Python 3.10 到 3.14。 Django 6.0 及更新版本至少需要 Python 3.12。
• PIP 套件管理器（隨 Python 3.4 及更新版本附贈）
• Microsoft ODBC 驅動程式 17 或 18 適用於 SQL Server，用於使用預設pyodbc驅動程式的資料庫別名。 請參閱下載 SQL Server 的 ODBC 驅動程式。

從 PyPI 安裝

用 PIP 安裝套件。 此指令也會自動安裝 Django、pyodbc、mssql-python 和 tzdata：

pip install mssql-django

要升級現有設施：

pip install --upgrade mssql-django

若要安裝特定版本：

pip install mssql-django==2.0.0

相依性與版本相容性

在 2.0 版本 mssql-django 中，套件的元資料包含以下相依性限制：

選擇資料庫驅動程式

pyodbc 是預設驅動程式，不需要設定。 如果要改為在 mssql-python 上執行資料庫別名，請將 OPTIONS 新增至該別名的 "python_driver": "mssql_python" 字典中。 別名可在同一個專案中使用不同的驅動程式。 關於行為差異及每個驅動程式忽略的選項，請參見 MSSQL-django 的「選擇資料庫驅動程式」。

確認安裝情況

安裝後，請確認套件安裝正確：

pip show mssql-django

預期產出：

Name: mssql-django
Version: 2.0.0
Summary: Django backend for Microsoft SQL Server

驗證預設 pyodbc 路徑所使用的 ODBC 層：

import pyodbc

print(f"pyodbc version: {pyodbc.version}")
print(f"Available ODBC drivers: {pyodbc.drivers()}")

使用虛擬環境

使用 Python 虛擬環境來隔離專案相依性：

python -m venv .venv

啟動虛擬環境：

.venv\Scripts\activate

source .venv/bin/activate

然後在虛擬環境中安裝 mssql-django ：

pip install mssql-django

平臺特定注意事項

使用預設 pyodbc 驅動程式的資料庫別名需要另外安裝 ODBC 驅動程式，安裝步驟會因作業系統而異。 使用 mssql-python 的別名不需要這些步驟。 相反地，請安裝 mssql-python 的平台前置條件，包括 macOS 上的 OpenSSL 以及 Linux 上的必要函式庫。

Windows 作業系統

使用從 .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 套件會自動安裝以下相依性：

後端則透過標準函式庫zoneinfo模組轉換時區感知datetime值。 zoneinfo會在作業系統有 IANA 時區資料庫時讀取該資料庫，否則改用 tzdata 套件；該套件涵蓋 Windows 和精簡容器映像。 pytz 不再是依賴性。

相關內容

• 快速入門：將 Django 連接到 SQL Server
• 選擇 mssql-django 的資料庫驅動程式
• MSSQL-Django 配置參考
• 使用 mssql-django 進行容器與本地開發
• 下載 SQL Server 的 ODBC 驅動程式
• Django 安裝指南