Install & Compatibility
Where this runs
tested against v3.31.4 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.050s · 65.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 6.5s · import 0.858s · 66MB
66MB installed
● package 66MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ydb
✓ import ydb
Primary import for the YDB SDK.
Driver
✓ import ydb
from ydb.driver import Driver
✗ from ydb import Driver
Driver is typically imported from `ydb.driver` or accessed via `ydb.Driver` after `import ydb` for type hints.
SessionPool
✓ from ydb.table import SessionPool
✗ from ydb import SessionPool
SessionPool is part of the table service, commonly imported from `ydb.table`.
dbapi
✓ import ydb.dbapi
✗ 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.
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()
ydb --version
Debug
Known issues
breakingStarting 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.fixUpgrade your Python environment to 3.8 or a newer supported version (e.g., `python3.8 -m pip install ydb`).
affects: >=3.26.0
gotchaAuthentication 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.fixUse 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.
affects: <3.0.0 (and users of outdated docs)
gotchaErrors 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]fixReview 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.
affects: >=3.26.8
gotchaWhen 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.fixPrefer `import ydb.dbapi` and use its `connect` function. Avoid installing `ydb-dbapi` as a standalone package unless specifically required for an older system.
affects: All versions
breakingThe 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.fixVerify 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.
affects: All versions
gotchaThe 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.fixVerify 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.
affects: All versions
Upgrade
Version history
3.31.4latest on PyPI · released Aug 27, 2026
Audit
Dependencies
grpciorequiredgRPC client library for communication with YDB.
grpcio-statusrequiredgRPC status codes handling.
protobufrequiredProtocol Buffers for data serialization. Version 4.x is currently supported.
google-authrequiredGoogle Authentication Library for Python, used for credential management.
google-api-corerequiredGoogle API Client Core library, used for API interactions.