Instalar mssql-python

O mssql-python driver é o driver oficial Python da Microsoft para SQL Server, Base de Dados SQL do Azure, Azure SQL Managed Instance e base de dados SQL no Microsoft Fabric. Instala 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 o gestor de pacotes pip, incluído no Python.
  • Para instalar com o gestor de pacotes conda.

Importante

O driver mssql-python utiliza DDBC (Direct Database Connectivity), que agrupa e gere internamente a camada ODBC. Não precisas de instalar o driver Microsoft ODBC para SQL Server separadamente.

Instalar a partir do PyPI

Instala 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 necessita em tempo de execução:

  • mssql-python-odbc disponibiliza os binários do Microsoft ODBC Driver 18.
  • mssql-python-rs inclui o runtime Rust que alimenta a cópia em massa e o provider 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 requerem mssql-python-rs. Para as fixações por versão, veja Requisitos de dependência.

Instalar a partir do 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 do Rust, pelo que o conda instala um pacote em vez de três. Executar pip list no ambiente ainda mostra mssql-python-odbc e mssql-python-rs, porque o pacote conda inclui os metadados do seu pacote. A Conda seleciona a build que corresponde à sua plataforma e à versão Python, e gere as atualizações:

conda update -c microsoft mssql-python

Instala o driver com conda ou pip num determinado ambiente, mas não ambos.

O pacote conda tem os seguintes requisitos de plataforma:

Platform Versões 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 o pip no Red Hat Enterprise Linux (RHEL) 8, Alpine Linux e outras distribuições com uma glibc mais antiga ou com musl.
macOS Intel, macOS Apple Silicon 3.10 a 3.15 macOS 15 e versões posteriores. As ligações encriptadas requerem OpenSSL instalado no sistema, conforme descrito em macOS. O driver não carrega o OpenSSL a partir do ambiente do conda.

Verifique a instalação

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

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

Produção esperada:

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

Notas específicas da plataforma

Windows

O motriz vem como uma roda pré-construída 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 gestor 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 noutras distribuições compatíveis com glibc 2.28 (AlmaLinux 8, Rocky Linux 8), o driver instala-se a partir do volante padrão manylinux_2_28 publicado para o PyPI.

Alpine Linux:

apk add libltdl krb5-libs libstdc++

macOS

O driver é fornecido como um universal2 binário grosso que corre nativamente tanto em Apple Silicon (arm64) como em Mac Intel (x86_64). Não precisas de uma instalação unixODBC separada.

O driver requer OpenSSL. Instale-o usando Homebrew:

brew install openssl

Se encontrar erros relacionados com SSL, certifique-se de que o OpenSSL está devidamente ligado:

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

Ambientes virtuais

Para evitar conflitos, instale pacotes Python num 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 controlador com dependências de desenvolvimento para contribuir para o mesmo:

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

Solucionar problemas de instalação

pip install falha com "não foi encontrada nenhuma distribuição correspondente"

Certifica-te de que estás a usar Python 3.10 ou posterior:

python --version

Se estiveres a usar uma versão mais antiga do Python, atualiza o Python ou usa o pyenv para gerir várias versões.

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

Se viresModuleNotFoundError: No module named 'mssql_python', verifica se estás a usar o mesmo ambiente Python onde instalaste o pacote.

pip show mssql-python

Erros de permissões no Linux/macOS

Se 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 a