該mssql-python驅動程式是 Microsoft 官方的 Python 驅動程式，適用於 Microsoft Fabric SQL Server、Azure SQL Database、Azure SQL 受控執行個體 及 SQL 資料庫。 在 Windows、Linux 或 macOS 上使用 pip 或 conda 安裝驅動程式。
先決條件
- 驅動程式需要 Python 3.10 或更新版本，且不支援較早的 Python 版本。
- 要用 PIP 安裝，使用隨 Python 附帶的 pip 套件管理器。
- 若要使用 conda 安裝，請使用 conda 套件管理器。
Important
mssql-python 驅動程式使用 DDBC （直接資料庫連接），該架構在內部整合並管理 ODBC 層。 你不需要另外安裝 Microsoft 的 SQL Server ODBC 驅動程式。
從 PyPI 安裝
使用 PIP 安裝驅動程式：
pip install mssql-python
要升級現有設施：
pip install --upgrade mssql-python
若要安裝特定版本：
pip install mssql-python==1.16.0
指令 pip install mssql-python 同時安裝驅動程式執行時所需的兩個伴隨套件：
-
mssql-python-odbc提供 Microsoft ODBC Driver 18 二進位檔。 -
mssql-python-rs隨附驅動批量複製的 Rust 執行環境及可選擇啟用的mssql-odbc提供者。
從 1.16.0 版本開始，mssql-python 會將兩個套件都釘選為確切版本。 早期版本則不要求 mssql-python-rs。 關於依版本分類的版本釘選，請參見 相依性需求。
從 conda 安裝
conda install -c microsoft mssql-python
conda 套件是一個自包含的套件。 它包含 Python 綁定、ODBC 驅動二進位檔和 Rust 執行時，所以 conda 只需安裝一個套件，而不是三個。 在環境中執行 pip list 時仍然顯示 mssql-python-odbc 和 mssql-python-rs，因為 conda 套件包含其套件中繼資料。 Conda 會選擇符合你平台和 Python 版本的建置，並管理升級：
conda update -c microsoft mssql-python
在特定環境中，使用 conda 或 pip 安裝驅動程式，但不要兩者都用。
conda 套件包含以下平台需求：
| Platform | Python 版本 | 需求 |
|---|---|---|
| Windows x64 | 3.10 到 3.15 | None. |
| Windows ARM64 | 3.12 到 3.15 | None. |
| Linux x64，Linux ARM64 | 3.10 到 3.15 | GLIBC 2.34 及更新版本。 在 Red Hat Enterprise Linux （RHEL） 8、Alpine Linux 及其他發行版搭配較舊的 glibc 或 musl 版本上使用 pip。 |
| macOS Intel，macOS Apple Silicon | 3.10 到 3.15 | macOS 15 及更新版本。 加密連線需要系統安裝 OpenSSL，如 macOS 頁面所述。 驅動程式不會從 conda 環境載入 OpenSSL。 |
確認安裝情況
安裝後，請確認驅動程式是否正常運作：
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}")
預期產出：
mssql-python version: 1.16.0
DB-API level: 2.0
Thread safety: 1
Parameter style: pyformat
平臺特定注意事項
Windows 作業系統
該驅動程式以預先建置的 wheel 套件形式提供，包含所有必要元件。
Linux
驅動程式需要特定的系統函式庫來進行 Kerberos 認證與動態載入。 使用你發行版的套件管理器安裝：
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
在 RHEL 8 和其他與 glibc 2.28 相容的發行版（AlmaLinux 8、Rocky Linux 8）上，驅動程式會從已發佈到 PyPI 的標準 manylinux_2_28 wheel 套件安裝。
Alpine Linux：
apk add libltdl krb5-libs libstdc++
macOS
驅動程式隨附為 universal2 通用二進位檔，可在 Apple Silicon（arm64）與 Intel（x86_64）Mac 電腦上原生執行。 你不需要另外安裝 UnixODBC。
驅動程式需要 OpenSSL。 使用 Homebrew 安裝：
brew install openssl
若遇到 SSL 相關錯誤，請確保 OpenSSL 連結正確：
export LDFLAGS="-L/opt/homebrew/opt/openssl/lib"
export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"
虛擬環境
為避免衝突，請在虛擬環境中安裝 Python 套件：
# 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
開發環境安裝
若要安裝包含開發相依套件的驅動程式，以便為此驅動程式做出貢獻：
git clone https://github.com/microsoft/mssql-python.git
cd mssql-python
pip install -e ".[dev]"
安裝問題的疑難排解
PIP 安裝失敗，顯示「無匹配發行版」
請確保你使用的是 Python 3.10 或更新版本：
python --version
如果你使用的是較舊的 Python 版本，建議升級 Python 或使用 pyenv 來管理多個版本。
安裝後匯入錯誤
如果你看到ModuleNotFoundError: No module named 'mssql_python'，請確認你使用的是安裝套件的同一個 Python 環境。
pip show mssql-python
Linux/macOS 上的權限錯誤
如果遇到權限錯誤，請避免使用 sudo pip。 請改用虛擬環境或 --user 旗標。
pip install --user mssql-python