YDB Python SDK

3.26.8 verified Tue May 12 auth: no python install: verified

The YDB Python SDK is the officially supported Python client for YDB (Yandex Database), a distributed SQL database. It provides comprehensive functionality for table operations, query execution, transaction management, authentication, async operations, topic operations for streaming data, and integrations with SQLAlchemy and DB-API 2.0. The library is actively maintained with frequent minor and patch releases, currently at version 3.26.8.

pip install ydb

Warnings

breaking Starting with version 3.26.0, the YDB Python SDK dropped compatibility with Python 3.7. Users on Python 3.7 or older must upgrade to Python 3.8 or higher. ↓

fix Upgrade your Python environment to 3.8 or a newer supported version (e.g., `python3.8 -m pip install ydb`).

gotcha Authentication is critical and has several methods. Older YDB Python SDK v2 documentation might refer to environment variables like `USE_METADATA_CREDENTIALS` or `SA_KEY_FILE` which are peculiar to deprecated versions. Always refer to the latest documentation for current authentication practices, which involve `ydb.credentials` classes. ↓

fix Use explicit credential providers from `ydb.credentials`, such as `AuthTokenCredentials`, `ServiceAccountCredentials.from_file`, `StaticCredentials`, or `AnonymousCredentials`. Modern environment variables like `YDB_TOKEN`, `YDB_USER`, and `YDB_PASSWORD` can also be used, depending on the credential provider.

gotcha Errors like "Sent message larger than max" are now non-retryable starting from version 3.26.8. This change prevents indefinite retries on errors that cannot be resolved by retrying. [cite: Changelog] ↓

fix Review your application logic to ensure messages adhere to YDB's size limits. Such errors indicate a fundamental data size issue rather than a transient network problem.

gotcha When using `ydb.dbapi` for DB-API 2.0 compliance, ensure you are importing `ydb.dbapi` from the main `ydb` SDK. While there's a separate `ydb-dbapi` package, the recommended approach for modern applications is to use the `ydb.dbapi` module directly provided by the `ydb` SDK. ↓

fix Prefer `import ydb.dbapi` and use its `connect` function. Avoid installing `ydb-dbapi` as a standalone package unless specifically required for an older system.

breaking The YDB driver failed to establish a connection or become ready within the specified timeout during `driver.wait()`. This typically indicates network issues, an unreachable YDB endpoint, incorrect endpoint configuration, or problems with the YDB cluster itself. ↓

fix Verify network connectivity to the YDB endpoint. Ensure the YDB endpoint address is correct and the YDB cluster is running and accessible. Check for firewall rules blocking the connection. Consider increasing the `timeout` value for `driver.wait()` if the network is latent, but investigate underlying connectivity issues first.

gotcha The YDB SDK encountered a `TimeoutError` while waiting for the driver to become ready, specifically during `driver.wait()`. This usually indicates a problem with network connectivity, an unreachable YDB endpoint, incorrect endpoint configuration, or an unresponsive YDB service, rather than a client-side library bug. ↓

fix Verify network connectivity to the YDB endpoint, ensure the endpoint URL is correct and accessible (e.g., no firewall issues), and check the status of the YDB service. Increase the `timeout` parameter for `driver.wait()` if the network or service is known to have higher latency.

Install compatibility verified last tested: 2026-05-12 v3.29.0 (up to date)

python os / libc status wheel install import disk mem side effects

3.10 alpine (musl) wheel - 1.65s 64.1M 24.8M clean

3.10 alpine (musl) - - 1.81s 64.0M 24.7M -

3.10 slim (glibc) wheel 7.2s 0.48s 64M 14.4M clean

3.10 slim (glibc) - - 0.48s 64M 14.3M -

3.11 alpine (musl) wheel - 2.06s 69.9M 26.4M clean

3.11 alpine (musl) - - 2.42s 69.8M 26.3M -

3.11 slim (glibc) wheel 5.4s 0.81s 70M 16.1M clean

3.11 slim (glibc) - - 0.84s 70M 16.1M -

3.12 alpine (musl) wheel - 2.10s 61.4M 26.3M clean

3.12 alpine (musl) - - 2.44s 61.4M 26.3M -

3.12 slim (glibc) wheel 4.5s 1.12s 61M 16.2M clean

3.12 slim (glibc) - - 1.39s 61M 16.2M -

3.13 alpine (musl) wheel - 2.03s 61.2M 27.3M clean

3.13 alpine (musl) - - 2.14s 61.0M 27.2M -

3.13 slim (glibc) wheel 4.8s 1.01s 61M 16.9M clean

3.13 slim (glibc) - - 1.16s 61M 16.9M -

3.9 alpine (musl) wheel - 1.59s 64.0M 24.9M clean

3.9 alpine (musl) - - 1.72s 63.6M 24.8M -

3.9 slim (glibc) wheel 8.0s 0.67s 64M 14.5M clean

3.9 slim (glibc) - - 0.64s 64M 14.5M -

Imports

ydb
```
import ydb
```
Primary import for the YDB SDK.
Driver
wrong
```
from ydb import Driver
```
correct
```
import ydb
from ydb.driver import Driver
```
Driver is typically imported from `ydb.driver` or accessed via `ydb.Driver` after `import ydb` for type hints.
SessionPool
wrong
```
from ydb import SessionPool
```
correct
```
from ydb.table import SessionPool
```
SessionPool is part of the table service, commonly imported from `ydb.table`.
dbapi
wrong
```
import ydb_dbapi
```
correct
```
import ydb.dbapi
```
The `ydb.dbapi` module provides a DB-API 2.0 compliant interface and is included with the `ydb` SDK. There is also a separate, older `ydb-dbapi` package which is not the primary way to use DB-API 2.0 with the main YDB SDK.
iam
```
import ydb.iam
```
Module for various Identity and Access Management (IAM) credentials.

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to initialize the YDB driver and session pool, connecting to a YDB instance. It prioritizes authentication via an environment variable `YDB_TOKEN` for `AuthTokenCredentials`, falling back to `AnonymousCredentials` if not provided, suitable for local setups. Replace `YDB_ENDPOINT` and `YDB_DATABASE` with your YDB instance details.

import os
import ydb

# Configure connection details from environment variables for flexibility
ENDPOINT = os.environ.get('YDB_ENDPOINT', 'grpcs://localhost:2135') # e.g., 'grpcs://ydb.example.com:2135'
DATABASE = os.environ.get('YDB_DATABASE', '/local/database') # e.g., '/path/to/my/db'
AUTH_TOKEN = os.environ.get('YDB_TOKEN')

def main():
    driver_config = ydb.DriverConfig(ENDPOINT, DATABASE)

    # Use token authentication if YDB_TOKEN is set, otherwise anonymous
    if AUTH_TOKEN:
        driver_config.credentials = ydb.credentials.AuthTokenCredentials(AUTH_TOKEN)
    else:
        # For local YDB or scenarios requiring no explicit auth (e.g., metadata service)
        driver_config.credentials = ydb.credentials.AnonymousCredentials()

    with ydb.Driver(driver_config) as driver:
        driver.wait(timeout=5, fail_fast=True)
        print("YDB driver initialized successfully.")

        # Create a session pool
        with ydb.SessionPool(driver) as session_pool:
            def execute_query(session):
                try:
                    session.execute('SELECT 1 as my_column;')
                    print("Query executed successfully.")
                except Exception as e:
                    print(f"Error executing query: {e}")

            session_pool.retry_operation_sync(execute_query)

if __name__ == '__main__':
    main()