Registry / database / python-tds

python-tds

JSON →
library1.17.1pypypi✓ verified 26d ago

Python-TDS is a pure Python DBAPI driver for Microsoft SQL Server, implementing the Tabular Data Stream (TDS) protocol. This cross-platform library eliminates dependencies on ADO or FreeTDS, offering features like MARS, bulk insert, table-valued parameters, and TLS/Kerberos support. The current version is 1.17.1, with active development and consistent releases.

pip install python-tds
INSTALL
IMPORT
SIG · PYTHON-TDS
P
python-tds
databasepythonv1.17.1
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.17.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
1/2 runs
1/2 runs
py 3.11
1/2 runs
1/2 runs
py 3.12
1/2 runs
1/2 runs
py 3.13
1/2 runs
1/2 runs
py 3.9
1/2 runs
1/2 runs
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

pytds
import pytds
The PyPI package is 'python-tds', but the import name is 'pytds'.

This quickstart demonstrates how to connect to a Microsoft SQL Server database using `python-tds`, execute a simple query, and fetch results. It uses environment variables for connection details for security and flexibility. The connection and cursor objects are managed using Python's `with` statement for automatic resource cleanup.

import os import pytds # --- Environment Variables (Replace with your actual values or secure fetching) --- SERVER = os.environ.get('SQL_SERVER', 'your_server.database.windows.net') DATABASE = os.environ.get('SQL_DATABASE', 'your_database') USER = os.environ.get('SQL_USER', 'your_username') PASSWORD = os.environ.get('SQL_PASSWORD', 'your_password') try: # Establish a connection using a context manager with pytds.connect(server=SERVER, database=DATABASE, user=USER, password=PASSWORD) as conn: print("Successfully connected to the database!") # Create a cursor object using a context manager with conn.cursor() as cursor: # Execute a simple query cursor.execute("SELECT 1 AS ConnectionTest") # Fetch the result result = cursor.fetchone() print(f"Query result: {result}") # Example: Fetch all results cursor.execute("SELECT 'Hello from Python-TDS' AS Message") all_results = cursor.fetchall() print(f"All results: {all_results}") except pytds.Error as e: print(f"Database error occurred: {e}") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingWhen connecting to SQL Server 2022 or newer with TDS 8.0 and `Encrypt=strict`, the `TrustServerCertificate` option cannot be set to `true`. Instead, `HostNameInCertificate` must be used for certificate validation.
fix
Ensure your `python-tds` client is up-to-date. Do not set `TrustServerCertificate` to `true`. Use `HostNameInCertificate` parameter in `pytds.connect` to specify the trusted certificate server name and ensure proper certificate validation.
affects: All versions when connecting to SQL Server 2022+ with strict encryption.
gotchaInserting binary data (e.g., into `VARBINARY` or `IMAGE` columns) requires wrapping the Python bytes object with `pytds.Binary()` to ensure correct type inference by the driver.
fix
For binary values, use `pytds.Binary(your_bytes_object)`. Example: `cursor.execute('INSERT INTO MyTable (BinaryColumn) VALUES (%s)', (pytds.Binary(data),))`
affects: All versions.
deprecatedThe NTLM authentication mechanism provided directly through `pytds.login` is deprecated due to its underlying dependency on the `ntlm-auth` package, which is also deprecated.
fix
It is recommended to use `SpnegoAuth` for NTLM/Kerberos authentication instead of the deprecated `pytds.login` approach.
affects: Versions 1.6+
gotchaA common 'Permission denied' error occurs during `pip install python-tds` if the user lacks write privileges to system Python directories.
fix
Use `pip install --user python-tds` to install into the user's home directory, or if installing system-wide, use `sudo pip install python-tds` (with caution).
affects: All versions on systems with strict permissions.
gotchaWhen connecting, ensure you correctly use the `server` and `dsn` parameters in `pytds.connect()`. `server` specifies the host, while `dsn` can include both host and instance name (e.g., `hostname\instance_name`).
fix
Use `server='your_host'` for default instances or when `dsn` is not required. Use `dsn='your_host\your_instance'` if connecting to a named instance, or `server='your_host', port=your_port` for specific ports.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tds'
The `python-tds` library has not been installed in the active Python environment.
fix
Install the library using pip: `pip install python-tds`
tds.dbapi.Error: ('Login failed for user', 'username', 'reason')
The provided username or password for connecting to the SQL Server is incorrect, or the user lacks necessary permissions.
fix
Verify the username and password used in the connection string and ensure the user has appropriate permissions to connect to the SQL Server and database.
tds.dbapi.Error: ('Connection timed out', '0', '0')
The SQL Server is unreachable from the client machine due to incorrect hostname/IP, port, firewall blocking, or the server itself is not running.
fix
Check the server's IP address/hostname, ensure the SQL Server is running, verify the port (default 1433) is open, and check firewall settings on both the client and server.
tds.dbapi.Error: ('Encryption not supported', '0', '0')
The SQL Server instance is configured to require encryption, but `python-tds` is either not configured for TLS/SSL or the server's certificate cannot be verified.
fix
Configure `python-tds` to use TLS by setting `encrypt=True` in the connection string, and potentially `trust_server_certificate=True` if using self-signed certificates or for development/testing: `tds.connect(host='...', database='...', user='...', password='...', encrypt=True, trust_server_certificate=True)`.
Upgrade
Version history
1.17.1latest on PyPI · released Sep 13, 2025
Audit
Dependencies
pyOpenSSLoptionalRequired for TLS connection encryption.
bitarrayoptionalProvides better performance for certain operations.
kerberosoptionalRequired for Kerberos authentication on non-Windows platforms (experimental).
Agent activity
46 hits · last 30 days
node
40
Resources
python-tds — pip install python-tds · libregistry