mssql-django 2.0 is on PyPI. This release adds Microsoft's new mssql-python driver as a second way to connect, moves the supported Python, Django, and SQL Server versions forward, and fixes several connection and query bugs that production teams hit.
pip install --upgrade mssql-django
Pick your driver, one database at a time
Until now, mssql-django spoke to SQL Server through pyodbc and an ODBC driver you installed yourself. That still works, and it's still the default. Version 2.0 adds a second path: mssql-python, Microsoft's Python driver for SQL Server.
You choose per database alias. Add one option to the alias you want to move:
DATABASES = {
"default": {
"ENGINE": "mssql",
"NAME": "appdb",
"HOST": "contoso.database.windows.net",
"PORT": "1433",
"OPTIONS": {
"python_driver": "mssql_python",
"extra_params": "Encrypt=yes",
},
},
"reporting": {
# No python_driver, so this alias stays on pyodbc.
"ENGINE": "mssql",
"NAME": "reportdb",
"HOST": "contoso.database.windows.net",
"PORT": "1433",
"OPTIONS": {
"driver": "ODBC Driver 18 for SQL Server",
},
},
}
ENGINE doesn't change. Remove the option and the alias is back on pyodbc. That's the whole rollback plan, which is the point: you can try the new driver on one database, run your test suite, and leave everything else alone.
The mssql-python path covers the day-to-day work: connections, pooling, retries, transactions and savepoints, datetimeoffset values, introspection, and Microsoft Entra ID authentication.
One practical difference worth calling out. On the mssql-python path, pip also installs the mssql-python-odbc companion package, which supplies Microsoft ODBC Driver 18 for SQL Server. There's no separate driver install, which takes a step out of container images and App Service deployments.
Know what changes before you switch
The two drivers aren't identical, and the differences are the reason we made this per alias instead of a global switch.
The mssql-python path ignores driver, dsn, host_is_server, and unicode_results. There's no ODBC Driver 17 fallback. It validates extra_params against an allowlist and rejects pyodbc-only keywords such as ColumnEncryption, APP, and Connect Timeout, so use the connection_timeout option instead of the last one. It also doesn't enable MARS, which means QuerySet.iterator() reads the full result into memory before yielding rows so a nested query can reuse the connection. On a large queryset, that memory is real. Budget for it.
Stay on pyodbc if you depend on a named DSN, FreeTDS, MARS, Always Encrypted through ColumnEncryption, or an ODBC driver version you manage yourself.
We cleaned up the version matrix
This is something we've wanted to get to for a while. mssql-django 2.0 supports Python 3.10 through 3.14, Django 5.2 through 6.1, and SQL Server 2017 through 2025, plus Azure SQL Database, Azure SQL Managed Instance, and SQL database in Microsoft Fabric. Django 6.0 and 6.1 need Python 3.12 or later.
Python 3.8 and 3.9 and Django 3.2 through 5.1 are no longer supported. The compatibility code is still in the tree, so nothing breaks the moment you upgrade, but those combinations aren't tested or listed.
Fixes
MARS settings are honored. If you set MARS_Connection=no in extra_params, the backend used to overwrite it with the Windows default and the connection failed. That's the bug frederiksoftware reported when connecting an on-premises Django app to a Microsoft Fabric Warehouse. The explicit value now wins, case-insensitively, so those connections work. To be clear about scope: this fixes the connection, it doesn't add full Warehouse support for migrations or other SQL Server features.
Bracket wildcards are escaped in F() expression lookups. A pattern lookup comparing two fields, such as filter(name__contains=F("code")), didn't escape the SQL Server [ wildcard, so bracket characters in your data were treated as wildcard syntax and matched the wrong rows. Thanks to @Khan3K for the fix.
Quotes are escaped in inspectdb schema names. inspectdb --schema produced malformed T-SQL for a schema name containing a single quote.
An empty HOST connects to localhost on the mssql-python path. Omitting HOST in Django settings leaves it as an empty string, which mssql-python rejected. It now resolves to localhost, matching the pyodbc behavior for local instances.
pytz is gone
Time zone handling moved to the standard library zoneinfo module, with the tzdata package supplying the IANA database where the operating system doesn't ship one: Windows, and minimal container images. This fixes offsets for zones with negative daylight saving offsets, and it drops a dependency.
Before you upgrade
mssql-python is a required dependency in 2.0 even when every alias uses pyodbc. That means mssql-django 2.0 installs only on platforms that have a compatible mssql-python distribution: Windows x64, Windows ARM64 with Python 3.11 and later, macOS 15 and later on Intel or Apple silicon, and Linux x64 or ARM64 with glibc 2.28 or later or musl 1.2 or later. SUSE Linux on ARM64 isn't supported. If you're outside that list, stay on 1.8.0.
Upgrade now
pip install --upgrade mssql-django
Thanks to @Khan3K and @frederiksoftware for the contributions in this release.