تحرير

Install mssql-python

The mssql-python driver is Microsoft's official Python driver for SQL Server, Azure SQL Database, Azure SQL Managed Instance, and SQL database in Microsoft Fabric. Install the driver on Windows, Linux, or macOS by using pip.

Prerequisites

  • The driver requires Python 3.10 or later and doesn't support earlier Python versions.
  • pip package manager (included with Python 3.4+).

Important

The mssql-python driver uses DDBC (Direct Database Connectivity), which bundles and manages the ODBC layer internally. You don't need to install the Microsoft ODBC Driver for SQL Server separately.

Install from PyPI

Install the driver using pip:

pip install mssql-python

To upgrade an existing installation:

pip install --upgrade mssql-python

To install a specific version:

pip install mssql-python==1.11.0

Verify the installation

After installation, verify the driver is working:

import mssql_python

print(f"mssql-python version: {mssql_python.__version__}")
print(f"DB-API level: {mssql_python.apilevel}")
print(f"Thread safety: {mssql_python.threadsafety}")
print(f"Parameter style: {mssql_python.paramstyle}")

Expected output:

mssql-python version: 1.11.0
DB-API level: 2.0
Thread safety: 1
Parameter style: pyformat

Platform-specific notes

Windows

The driver ships as a prebuilt wheel that includes all necessary components.

Linux

The driver requires certain system libraries for Kerberos authentication and dynamic loading. Install them using your distribution's package manager:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2

Red Hat/CentOS/Fedora:

sudo dnf install libtool-ltdl krb5-libs

Note

On RHEL 8 and other glibc 2.28 compatible distributions (AlmaLinux 8, Rocky Linux 8), the driver installs from the standard manylinux_2_28 wheel published to PyPI.

Alpine Linux:

apk add libltdl krb5-libs

macOS

The driver ships as a universal2 fat binary that runs natively on both Apple Silicon (arm64) and Intel (x86_64) Macs. You don't need a separate unixODBC install.

The driver requires OpenSSL. Install it by using Homebrew:

brew install openssl

If you encounter SSL-related errors, ensure OpenSSL is properly linked:

export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"

Virtual environments

To avoid conflicts, install Python packages in a virtual environment:

# Create a virtual environment
python -m venv .venv

# Activate it (Windows)
.venv\Scripts\activate

# Activate it (Linux/macOS)
source .venv/bin/activate

# Install the driver
pip install mssql-python

Development installation

To install the driver with development dependencies for contributing to the driver:

git clone https://github.com/microsoft/mssql-python.git
cd mssql-python
pip install -e ".[dev]"

Troubleshoot installation issues

pip install fails with "no matching distribution"

Ensure you're using Python 3.10 or later:

python --version

If you're using an older Python version, upgrade Python or use pyenv to manage multiple versions.

Import error after installation

If you see ModuleNotFoundError: No module named 'mssql_python', verify you're using the same Python environment where you installed the package.

pip show mssql-python

Permission errors on Linux/macOS

If you encounter permission errors, avoid using sudo pip. Instead, use a virtual environment or the --user flag.

pip install --user mssql-python

Related content

  • Last updated on