mssql-django 包是微软官方支持的 Django 数据库后端，适用于 SQL Server、Azure SQL 数据库、Azure SQL 托管实例 和 Microsoft Fabric 中的 SQL 数据库。 本文介绍如何安装包及其依赖项。
先决条件
- Python 3.10 到 3.14。 Django 6.0及以后版本至少需要Python 3.12。
- pip 包管理器（Python 3.4 及更高版本随附）
-
适用于 SQL Server 的 Microsoft ODBC 驱动程序 17 或 18，适用于使用默认
pyodbc驱动程序的数据库别名。 请参阅下载适用于 SQL Server 的 ODBC 驱动程序。
Important
mssql-django 2.0 需要 mssql-python 1.15.0 或更高版本，即使每个数据库别名都使用 pyodbc。 该软件包仅安装在兼容 mssql-python 发行版的平台上。 其他平台的项目仍保留在1.8.0版本。 关于平台列表，请参见 mssql-django 支持和生命周期。
从 PyPI 安装
使用 pip 安装该软件包。 该命令还会自动安装 Django、pyodbc、mssql-python 以及 tzdata：
pip install mssql-django
升级现有安装：
pip install --upgrade mssql-django
安装特定版本：
pip install mssql-django==2.0.0
依赖项和版本兼容性
对于 mssql-django 2.0，包元数据包含以下依赖约束：
| 组件 | 版本指南 |
|---|---|
| Python | 3.10 到 3.14 |
| Django |
>=5.2 和 <6.2 |
pyodbc |
>=3.0 |
mssql-python |
>=1.15.0 |
tzdata |
作为依赖项安装 |
Tip
让 pip 解析兼容版本，除非你有经过测试的锁定文件。 固定旧 pyodbc 版本可能会导致运行时问题，即使安装成功也是如此。
选择数据库驱动
pyodbc 是默认驱动，无需配置。 如果要改为在 mssql-python 上运行某个数据库别名，请将 "python_driver": "mssql_python" 添加到该别名的 OPTIONS 字典中。 别名可以在同一项目中使用不同的驱动程序。 关于行为差异以及每个驱动忽略的选项，请参见 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()}")
注释
mssql-django 后端会在 Django 的数据库路由系统中被自动配置。 不要直接在应用程序代码中导入它。 而应在ENGINE配置中将mssql设置为DATABASES。
使用虚拟环境
使用Python虚拟环境隔离项目依赖项：
python -m venv .venv
激活虚拟环境：
.venv\Scripts\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 驱动程序。 有关特定于平台的说明，请参阅安装适用于 SQL Server（Linux）的 Microsoft ODBC 驱动程序。
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 数据库驱动程序 |
mssql-python |
需主动启用的 Python 数据库驱动程序，无条件安装 |
tzdata |
用于标准库 zoneinfo 模块的 IANA 时区数据库 |
后端通过标准库zoneinfo模块转换时区感知datetime值。
zoneinfo 会在存在时读取操作系统的 IANA 时区数据库，否则会回退到 tzdata 包，该包适用于 Windows 和精简容器镜像。
pytz 不再是依赖项。