mssql-django 包是微软官方支持的 Django 数据库后端，适用于 SQL Server、Azure SQL 数据库、Azure SQL 托管实例 和 Microsoft Fabric 中的 SQL 数据库。 本文介绍如何安装包及其依赖项。
先决条件
- Python 3.8 或更高版本。 Django 6.0 需要Python 3.12 及更高版本。
- pip 包管理器（Python 3.4 及更高版本随附）
- 适用于 SQL Server 的 Microsoft ODBC Driver 17 或 18。 请参阅下载适用于 SQL Server 的 ODBC 驱动程序。
Important
mssql-python与驱动程序不同，mssql-django需要外部 ODBC 驱动程序。 在配置 Django 项目之前，请安装 Microsoft ODBC Driver for SQL Server。
从 PyPI 安装
使用 pip 安装包。 此命令还会自动安装 Django、pyodbc 和 pytz：
pip install mssql-django
升级现有安装：
pip install --upgrade mssql-django
安装特定版本：
pip install mssql-django==1.7.4
依赖项和版本兼容性
在1.7.4版本 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.4
Summary: Django backend for Microsoft SQL Server
从 Python 中通过测试 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
特定于平台的注释
ODBC 驱动程序安装步骤因操作系统而异。
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 数据库驱动程序 |
pytz |
时区支持 |
后端在内部导入 pytz，以便针对 SQL Server 转换带时区信息的 datetime 值，因此即使你的 Django 项目使用带有标准库 zoneinfo 模块的 USE_TZ=True，pytz 仍然是必需的运行时依赖。