Install & Compatibility
Where this runs
tested against v1.7.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 73.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.7s · import 0.000s · 71MB
71MB installed
● package 71MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ENGINE setting
✓ DATABASES = {
'default': {
'ENGINE': 'mssql',
# ... other settings
}
}
✗ 'ENGINE': 'sql_server.pyodbc'
The correct ENGINE string for mssql-django is 'mssql'. 'sql_server.pyodbc' was used by older, community-maintained predecessors like django-mssql-backend.
To use `mssql-django`, configure your Django project's `settings.py` file. The `ENGINE` value must be set to 'mssql'. Ensure your database credentials, host, and an appropriate ODBC driver are specified in the `DATABASES` dictionary. For Azure SQL, additional `extra_params` in `OPTIONS` might be necessary for encryption and certificate trust.
import os
DATABASES = {
'default': {
'ENGINE': 'mssql',
'NAME': 'your_database_name',
'USER': os.environ.get('DB_USER', 'your_db_user'),
'PASSWORD': os.environ.get('DB_PASSWORD', 'your_db_password'),
'HOST': os.environ.get('DB_HOST', 'your_server.database.windows.net'),
'PORT': os.environ.get('DB_PORT', ''), # Default port 1433 if empty
'OPTIONS': {
'driver': os.environ.get('ODBC_DRIVER', 'ODBC Driver 18 for SQL Server'),
# 'isolation_level': 'READ UNCOMMITTED', # Example option
# 'extra_params': 'Encrypt=yes;TrustServerCertificate=no;', # Example for Azure SQL
},
}
}
# Optional: Disable pyodbc's connection pooling
# DATABASE_CONNECTION_POOLING = False
Debug
Known issues
breakingDjango version compatibility is critical. `mssql-django` 1.7 provides full support for Django 6.0, while earlier versions support specific Django releases (e.g., 1.6 for Django 5.1/5.2, 1.4 for Django 5.0). Upgrading your Django version without a compatible `mssql-django` can lead to runtime errors or failed migrations.fixAlways check the `mssql-django` release notes or PyPI page for the supported Django and Python versions before upgrading either library. Upgrade `mssql-django` to a version compatible with your Django release.
affects: < 1.7 with Django 6.0, specific versions for other Django releases
deprecatedDjango 5.1 deprecated `Meta.index_together` in favor of `Meta.indexes`. Older `mssql-django` versions (e.g., pre-1.6) or existing migrations using `index_together` with Django 5.1+ can cause `AttributeError` during migrations.fixUpgrade to `mssql-django` 1.6 or newer. For existing migrations, replace `Meta.index_together` with `Meta.indexes` in your models and generate new migrations, then apply them.
affects: Django 5.1+ with mssql-django < 1.6
gotchaTimezone support (introduced in v1.2) may require manual migrations for existing `DATETIME` fields, especially if converting to `DATETIMEOFFSET`. There have been known issues with `USE_TZ=True` and `settings.TIME_ZONE != 'UTC'` in versions 1.2 and newer, which were addressed in recent updates.fixRefer to the `mssql-django` wiki page on Timezone Support for manual migration steps if upgrading from pre-1.2. For `USE_TZ=True` issues, ensure you are on the latest `mssql-django` version, which includes fixes for `DATETIMEOFFSET` handling.
affects: 1.2 and newer (especially pre-PR #484 fixes)
gotchaNative UUID field support was temporarily added in v1.4.1 (mapping to SQL Server `uniqueidentifier`) but reverted in v1.4.2 to restore the original `char(32)` behavior due to internal issues. This can lead to unexpected type mappings or migration failures if you rely on `uniqueidentifier` in `1.4.1` and then downgrade or upgrade past `1.4.2`.fixBe aware that `UUIDField` will typically map to `char(32)`. If you require `uniqueidentifier`, manual database-level type changes or custom field implementations might be necessary, and ensure thorough testing across `mssql-django` versions around this change.
affects: 1.4.1, 1.4.2
gotchaThe `return_rows_bulk_insert` option, which controls whether rows are returned after a bulk insert, changed its default to `False` in version 1.2. If you relied on this behavior, or if your tables have triggers, this setting is crucial.fixIf your application expects rows to be returned after bulk inserts, explicitly set `return_rows_bulk_insert: True` in the `OPTIONS` dictionary of your database configuration. Note that it must be `False` if tables have triggers to avoid insertion failures.
affects: 1.2 and newer
gotchaA Microsoft ODBC Driver for SQL Server (e.g., 'ODBC Driver 17 for SQL Server' or 'ODBC Driver 18 for SQL Server') must be installed separately on the system where the Django application runs. Without it, `pyodbc` cannot establish a connection.fixDownload and install the appropriate Microsoft ODBC Driver for SQL Server for your operating system. Ensure the driver name in your Django `OPTIONS` matches the installed driver (e.g., `{'driver': 'ODBC Driver 18 for SQL Server'}`). affects: All
Upgrade
Version history
1.7.2latest on PyPI · released May 22, 2026
Audit
Dependencies
DjangorequiredCore dependency for a Django database backend, automatically installed.
pyodbcrequiredRequired for Python ODBC connectivity to SQL Server, automatically installed.
pytzrequiredRequired for timezone support, automatically installed.
Microsoft ODBC Driver for SQL ServerrequiredExternal system dependency, must be installed separately for pyodbc to function.