Getting started

Getting started

Requirements

mssql-django 2.0 supports:

Component	Supported versions
Django	5.2, 6.0, 6.1
Python	CPython 3.10-3.14; Django 6.0 and 6.1 require Python 3.12+
Platforms	Windows x64; Windows ARM64 with Python 3.11+; macOS 15+ on Intel or Apple silicon; Linux x64/ARM64 with glibc 2.28+ or musl 1.2+
SQL Server	2017, 2019, 2022, 2025
Azure SQL	Database, Managed Instance, SQL Database in Microsoft Fabric
Database drivers	pyodbc (default), mssql-python

mssql-django 2.0 requires a platform supported by mssql-python. SUSE Linux ARM64 is not supported. Other environments must remain on mssql-django 1.8.0.

Installation

Install mssql-django:

pip install mssql-django

This installs Django, mssql-python 1.15.0 or newer, pyodbc, and tzdata.

The default pyodbc path requires Microsoft ODBC Driver 18 or 17 for SQL Server to be installed separately. The mssql-python path uses the mssql-python-odbc companion package installed automatically by pip, which supplies Microsoft ODBC Driver 18. Also install the mssql-python platform prerequisites, including OpenSSL on macOS and the required Linux libraries.

Configure Django

Set ENGINE to "mssql" in your Django project's settings.py:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "mydb",
        "USER": "user@myserver",
        "PASSWORD": "password",
        "HOST": "myserver.database.windows.net",
        "PORT": "",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

# Set this to False before opening connections to disable pooling for both drivers.
DATABASE_CONNECTION_POOLING = False

pyodbc remains the default. To select mssql-python for one database alias, add python_driver to that alias:

"OPTIONS": {
    "python_driver": "mssql_python",
}

Omit python_driver or set it to "pyodbc" to use pyodbc. Different database aliases can use different drivers in the same application. The driver option and Driver 17 fallback apply only to pyodbc.

See the README configuration reference for all settings and driver-specific behavior.