Instalar mssql-python

O mssql-python driver é o driver oficial Python da Microsoft para SQL Server, Banco de Dados SQL do Azure, Instância Gerenciada de SQL do Azure e banco de dados SQL no Microsoft Fabric. Instale o driver no Windows, Linux ou macOS usando pip ou conda.

Pré-requisitos

  • O driver requer Python 3.10 ou posterior e não suporta versões anteriores de Python.
  • Para instalar com pip, use o gerenciador de pacotes pip, que está incluído no Python.
  • Para instalar com o gerenciador de pacotes conda.

Importante

O driver mssql-python usa DDBC (Direct Database Connectivity), que agrupa e gerencia internamente a camada ODBC. Você não precisa instalar o driver Microsoft ODBC para SQL Server separadamente.

Instalar via PyPI

Instale o driver usando pip:

pip install mssql-python

Para atualizar uma instalação existente:

pip install --upgrade mssql-python

Para instalar uma versão específica:

pip install mssql-python==1.16.0

O pip install mssql-python comando também instala dois pacotes complementares que o driver requer em tempo de execução:

  • mssql-python-odbcinclui os binários do Driver ODBC 18 da Microsoft.
  • mssql-python-rs inclui o runtime Rust que alimenta a cópia em massa e o provedor opt-in mssql-odbc .

A partir da versão 1.16.0, mssql-python fixa versões exatas de ambos os pacotes. Versões anteriores não exigem mssql-python-rs. Para os marcadores por versão, confira Requisitos de dependência.

Instalar com o conda

O driver também está disponível no canal microsoft em Anaconda.org:

conda install -c microsoft mssql-python

O pacote Conda é um pacote autônomo. Inclui os bindings em Python, os binários dos drivers ODBC e o runtime Rust, então o conda instala um pacote em vez de três. Ao executar pip list no ambiente, ainda aparecem mssql-python-odbc e mssql-python-rs, porque o pacote conda inclui os metadados do pacote deles. A Conda seleciona a build que combina com sua plataforma e versão em Python, e gerencia as atualizações:

conda update -c microsoft mssql-python

Instale o driver com conda ou pip em um determinado ambiente, não com ambos.

O pacote conda possui os seguintes requisitos de plataforma:

Platform Versões do Python Requirement
Windows x64 3.10 a 3.15 None.
Windows ARM64 3.12 a 3.15 None.
Linux x64, Linux ARM64 3.10 a 3.15 Glibc 2.34 e versões posteriores. Use pip no Red Hat Enterprise Linux (RHEL) 8, Alpine Linux e outras distribuições com um glibc mais antigo ou com musl.
macOS Intel, macOS Apple Silicon 3.10 a 3.15 macOS 15 e versões posteriores. Conexões criptografadas requerem OpenSSL instalado no sistema, conforme descrito no macOS. O driver não carrega o OpenSSL pelo ambiente da Conda.

Verificar a instalação

Após a instalação, verifique se o driver está funcionando:

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}")

Resultado esperado:

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

Notas específicas da plataforma

Windows

O driver é disponibilizado como um wheel pré-compilado que inclui todos os componentes necessários.

Linux

O driver requer certas bibliotecas do sistema para autenticação Kerberos e carregamento dinâmico. Instale-os usando o gerenciador de pacotes da sua distribuição:

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

No RHEL 8 e em outras distribuições compatíveis com glibc 2.28 (AlmaLinux 8, Rocky Linux 8), o driver é instalado a partir do wheel padrão manylinux_2_28 publicado no PyPI.

Alpine Linux:

apk add libltdl krb5-libs libstdc++

macOS

O driver é fornecido como um universal2 binário universal executado nativamente tanto em Macs Apple Silicon (arm64) quanto em Intel (x86_64). Você não precisa de uma instalação separada do unixODBC.

O driver requer OpenSSL. Instale usando Homebrew:

brew install openssl

Se você encontrar erros relacionados a SSL, certifique-se de que o OpenSSL esteja devidamente vinculado:

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

Ambientes virtuais

Para evitar conflitos, instale pacotes Python em um ambiente virtual:

# 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

Instalação de desenvolvimento

Para instalar o driver com as dependências de desenvolvimento para contribuir com o driver:

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

Solucionar problemas de instalação

Instalação de PIP falha com o erro "sem distribuição correspondente"

Certifique-se de que você está usando Python 3.10 ou posterior:

python --version

Se você está usando uma versão antiga do Python, atualize o Python ou use o pyenv para gerenciar várias versões.

Erro de importação após a instalação

Se você vir ModuleNotFoundError: No module named 'mssql_python', verifique se está usando o mesmo ambiente do Python em que instalou o pacote.

pip show mssql-python

Erros de permissão no Linux/macOS

Se você encontrar erros de permissão, evite usar sudo pip. Em vez disso, use um ambiente virtual ou a --user bandeira.

pip install --user mssql-python

Conteúdo relacionado

  • Última atualização em