{"id":1042,"library":"ydb","title":"YDB Python SDK","description":"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.","status":"active","version":"3.26.8","language":"python","source_language":"en","source_url":"https://github.com/ydb-platform/ydb-python-sdk","tags":["database","distributed-sql","nosql","cloud","sql","yandex"],"install":[{"cmd":"pip install ydb","lang":"bash","label":"Install YDB Python SDK"}],"dependencies":[{"reason":"gRPC client library for communication with YDB.","package":"grpcio","optional":false},{"reason":"gRPC status codes handling.","package":"grpcio-status","optional":false},{"reason":"Protocol Buffers for data serialization. Version 4.x is currently supported.","package":"protobuf","optional":false},{"reason":"Google Authentication Library for Python, used for credential management.","package":"google-auth","optional":false},{"reason":"Google API Client Core library, used for API interactions.","package":"google-api-core","optional":false}],"imports":[{"note":"Primary import for the YDB SDK.","symbol":"ydb","correct":"import ydb"},{"note":"Driver is typically imported from `ydb.driver` or accessed via `ydb.Driver` after `import ydb` for type hints.","wrong":"from ydb import Driver","symbol":"Driver","correct":"import ydb\nfrom ydb.driver import Driver"},{"note":"SessionPool is part of the table service, commonly imported from `ydb.table`.","wrong":"from ydb import SessionPool","symbol":"SessionPool","correct":"from ydb.table import SessionPool"},{"note":"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.","wrong":"import ydb_dbapi","symbol":"dbapi","correct":"import ydb.dbapi"},{"note":"Module for various Identity and Access Management (IAM) credentials.","symbol":"iam","correct":"import ydb.iam"}],"quickstart":{"code":"import os\nimport ydb\n\n# Configure connection details from environment variables for flexibility\nENDPOINT = os.environ.get('YDB_ENDPOINT', 'grpcs://localhost:2135') # e.g., 'grpcs://ydb.example.com:2135'\nDATABASE = os.environ.get('YDB_DATABASE', '/local/database') # e.g., '/path/to/my/db'\nAUTH_TOKEN = os.environ.get('YDB_TOKEN')\n\ndef main():\n    driver_config = ydb.DriverConfig(ENDPOINT, DATABASE)\n\n    # Use token authentication if YDB_TOKEN is set, otherwise anonymous\n    if AUTH_TOKEN:\n        driver_config.credentials = ydb.credentials.AuthTokenCredentials(AUTH_TOKEN)\n    else:\n        # For local YDB or scenarios requiring no explicit auth (e.g., metadata service)\n        driver_config.credentials = ydb.credentials.AnonymousCredentials()\n\n    with ydb.Driver(driver_config) as driver:\n        driver.wait(timeout=5, fail_fast=True)\n        print(\"YDB driver initialized successfully.\")\n\n        # Create a session pool\n        with ydb.SessionPool(driver) as session_pool:\n            def execute_query(session):\n                try:\n                    session.execute('SELECT 1 as my_column;')\n                    print(\"Query executed successfully.\")\n                except Exception as e:\n                    print(f\"Error executing query: {e}\")\n\n            session_pool.retry_operation_sync(execute_query)\n\nif __name__ == '__main__':\n    main()","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.8 or a newer supported version (e.g., `python3.8 -m pip install ydb`).","message":"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.","severity":"breaking","affected_versions":">=3.26.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<3.0.0 (and users of outdated docs)"},{"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.","message":"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]","severity":"gotcha","affected_versions":">=3.26.8"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T22:58:02.058Z","next_check":"2026-06-27T00:00:00.000Z","problems":[],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.29.0","cli_name":"ydb","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"3.29.0","pypi_latest":"3.29.0","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"ydb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.65,"mem_mb":24.8,"disk_size":"64.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"ydb","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.81,"mem_mb":24.7,"disk_size":"64.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"ydb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":7.2,"import_time_s":0.48,"mem_mb":14.4,"disk_size":"64M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"ydb","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.48,"mem_mb":14.3,"disk_size":"64M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"ydb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":2.06,"mem_mb":26.4,"disk_size":"69.9M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"ydb","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.42,"mem_mb":26.3,"disk_size":"69.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"ydb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":5.4,"import_time_s":0.81,"mem_mb":16.1,"disk_size":"70M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"ydb","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.84,"mem_mb":16.1,"disk_size":"70M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"ydb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":2.1,"mem_mb":26.3,"disk_size":"61.4M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"ydb","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.44,"mem_mb":26.3,"disk_size":"61.4M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"ydb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.5,"import_time_s":1.12,"mem_mb":16.2,"disk_size":"61M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"ydb","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.39,"mem_mb":16.2,"disk_size":"61M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"ydb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":2.03,"mem_mb":27.3,"disk_size":"61.2M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"ydb","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":2.14,"mem_mb":27.2,"disk_size":"61.0M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"ydb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":4.8,"import_time_s":1.01,"mem_mb":16.9,"disk_size":"61M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"ydb","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.16,"mem_mb":16.9,"disk_size":"61M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"ydb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":1.59,"mem_mb":24.9,"disk_size":"64.0M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"ydb","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":1.72,"mem_mb":24.8,"disk_size":"63.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"ydb","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":8,"import_time_s":0.67,"mem_mb":14.5,"disk_size":"64M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"ydb","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.64,"mem_mb":14.5,"disk_size":"64M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}