Edit

Install mssql-django

The mssql-django package is the official Microsoft-supported Django database backend for SQL Server, Azure SQL Database, Azure SQL Managed Instance, and SQL database in Microsoft Fabric. This article explains how to install the package and its dependencies.

Prerequisites

  • Python 3.8 or later. Django 6.0 requires Python 3.12 and later versions.
  • pip package manager (included with Python 3.4 and later versions)
  • Microsoft ODBC Driver 17 or 18 for SQL Server. See Download ODBC Driver for SQL Server.

Important

Unlike the mssql-python driver, mssql-django requires an external ODBC driver. Install the Microsoft ODBC Driver for SQL Server before configuring your Django project.

Install from PyPI

Install the package using pip. This command also installs Django, pyodbc, and pytz automatically:

pip install mssql-django

To upgrade an existing installation:

pip install --upgrade mssql-django

To install a specific version:

pip install mssql-django==1.7.3

Dependency and version compatibility

For mssql-django 1.7.3, the package metadata includes these dependency constraints:

Component Version guidance
Python 3.8 or later versions
Django >=3.2 and <6.1
pyodbc >=3.0
pytz Installed as a dependency

Tip

Let pip resolve compatible versions unless you have a tested lock file. Pinning an older pyodbc version can cause runtime issues even when installation succeeds.

Verify the installation

After installation, verify the package is installed correctly:

pip show mssql-django

Expected output:

Name: mssql-django
Version: 1.7.3
Summary: Django backend for Microsoft SQL Server

Verify installation from Python by testing the ODBC layer:

import pyodbc

print(f"pyodbc version: {pyodbc.version}")
print(f"Available ODBC drivers: {pyodbc.drivers()}")

Note

The mssql-django backend is automatically configured in Django's database routing system. Don't import it directly in application code. Instead, set the ENGINE to mssql in your DATABASES configuration.

Use a virtual environment

Use a Python virtual environment to isolate project dependencies:

python -m venv .venv

Activate the virtual environment:

.venv\Scripts\activate

Then install mssql-django inside the virtual environment:

pip install mssql-django

Platform-specific notes

The ODBC driver installation steps vary by operating system.

Windows

Install the Microsoft ODBC Driver 18 for SQL Server using the .msi installer from Download ODBC Driver for SQL Server.

Linux

Install the ODBC driver using your distribution's package manager. See Install the Microsoft ODBC driver for SQL Server (Linux) for platform-specific instructions.

macOS

Install the ODBC driver with Homebrew:

brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
HOMEBREW_ACCEPT_EULA=Y brew install msodbcsql18

Dependencies

The mssql-django package automatically installs the following dependencies:

Package Purpose
Django Web framework
pyodbc ODBC database driver for Python
pytz Time zone support

pytz remains a package dependency for compatibility, but most modern Django time zone workflows use USE_TZ=True with Django's built-in time zone handling.

Related content

  • Last updated on