mssql-python 이 드라이버는 Microsoft Fabric SQL Server, Azure SQL Database, Azure SQL Managed Instance, SQL 데이터베이스에 대한 Microsoft 공식 Python 드라이버입니다. Windows, Linux, macOS에서 pip이나 conda를 사용해 드라이버를 설치하세요.
사전 요구 사항
- 이 드라이버는 Python 3.10 이상이 필요하며, 이전 Python 버전은 지원하지 않습니다.
- pip로 설치하려면 Python에 포함된 pip 패키지 관리자
- conda로 설치하려면 conda 패키지 관리자를 사용하세요.
중요합니다
mssql-python 드라이버는 DDBC (Direct Database Connectivity)를 사용하며, ODBC 계층을 내부적으로 번들링하고 관리합니다. Microsoft ODBC 드라이버 for SQL Server를 별도로 설치할 필요는 없습니다.
PyPi에서 설치
PIP를 사용해 드라이버를 설치하세요:
pip install mssql-python
기존 설치를 업그레이드하려면 다음을 수행합니다.
pip install --upgrade mssql-python
특정 버전을 설치하려면
pip install mssql-python==1.16.0
이 명령어는 또한 런타임에 드라이버가 필요로 하는 두 개의 함께 제공되는 패키지를 설치합니다:
-
mssql-python-odbcMicrosoft ODBC Driver 18 바이너리를 제공합니다. -
mssql-python-rs에는 대량 복사를 구동하는 Rust 런타임과 옵트인mssql-odbc제공자가 제공됩니다.
버전 1.16.0부터 mssql-python는 두 패키지의 정확한 버전을 핀으로 고정합니다. 이전 버전에서는 mssql-python-rs이 필요하지 않습니다. 버전별 핀에 대해서는 의존성 요구사항을 참조하세요.
conda에서 설치
드라이버는 microsoft의 채널에서도 사용할 수 있습니다:
conda install -c microsoft mssql-python
콘다 패키지는 독립형 패키지입니다. Python 바인딩, ODBC 드라이버 바이너리, Rust 런타임이 포함되어 있어서 conda가 세 개 대신 하나의 패키지를 설치합니다. 환경에서 pip list를 실행해도 conda 패키지에 해당 패키지 메타데이터가 포함되어 있기 때문에 여전히 mssql-python-rs 및 mssql-python-odbc가 표시됩니다. Conda는 귀하의 플랫폼과 Python 버전에 맞는 빌드를 선택하고, 업그레이드를 관리합니다:
conda update -c microsoft mssql-python
주어진 환경에서 conda나 pip 중 하나로 드라이버를 설치하세요. 둘 다 사용하지 마세요.
콘다 패키지에는 다음과 같은 플랫폼 요구사항이 있습니다:
| Platform | Python 버전 | Requirement |
|---|---|---|
| Windows x64 | 3.10부터 3.15까지 | 없음. |
| Windows ARM64 | 3.12부터 3.15까지 | 없음. |
| 리눅스 x64, 리눅스 ARM64 | 3.10부터 3.15까지 | GLIBC 2.34 및 이후 버전. glibc가 오래되었거나 musl을 사용하는 Red Hat Enterprise Linux(RHEL) 8, Alpine Linux 및 기타 배포판에서 pip을 사용하세요. |
| macOS 인텔, macOS 애플 실리콘 | 3.10부터 3.15까지 | macOS 15 이후 버전입니다. 암호화된 연결에는 macOS 문서에 설명된 대로 시스템에 OpenSSL이 설치되어 있어야 합니다. 드라이버는 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
드라이버는 필요한 모든 부품이 포함된 사전 제작된 바퀴로 배송됩니다.
Linux
드라이버는 Kerberos 인증 및 동적 로딩을 위해 특정 시스템 라이브러리를 요구합니다. 배포판의 패키지 관리자를 사용해 설치하세요:
Ubuntu/Debian:
sudo apt-get update
sudo apt-get install libltdl7 libkrb5-3 libgssapi-krb5-2
레드 햇/센트OS/페도라:
sudo dnf install libtool-ltdl krb5-libs
비고
RHEL 8 및 기타 glibc 2.28 호환 배포판(AlmaLinux 8, Rocky Linux 8)에서는 드라이버가 PyPI에 배포된 표준 manylinux_2_28 휠에서 설치됩니다.
알파인 리눅스:
apk add libltdl krb5-libs libstdc++
macOS
드라이버는 Apple Silicon(arm64) 및 Intel(x86_64) Mac 모두에서 네이티브로 실행되는 universal2 팻 바이너리 형태로 제공됩니다. 별도의 유닉스 ODBC 설치가 필요하지 않습니다.
드라이버는 OpenSSL을 필요로 합니다. 홈브류를 사용해 설치하세요:
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