{"id":491,"library":"google-cloud-bigtable","title":"Google Cloud Bigtable Python Client Library","description":"The `google-cloud-bigtable` library is the official Python client for Google Cloud Bigtable, a fully managed, scalable NoSQL database service designed for high-performance and low-latency applications. It powers many core Google services like Search, Analytics, Maps, and Gmail. Currently at version 2.35.0, the library is actively maintained with frequent updates, adding new features and ensuring compatibility with the Bigtable service.","status":"active","version":"2.35.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/python-bigtable","tags":["google-cloud","bigtable","database","nosql","client-library","gcp"],"install":[{"cmd":"pip install google-cloud-bigtable","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Client","correct":"from google.cloud import bigtable"},{"note":"Introduced in v2.23.0 for asyncio-based applications; generally not recommended for synchronous codebases.","symbol":"BigtableDataClientAsync","correct":"from google.cloud.bigtable.data import BigtableDataClientAsync"}],"quickstart":{"code":"import os\nfrom google.cloud import bigtable\nfrom google.cloud.bigtable import row\nfrom google.cloud.bigtable import column_family\n\n# Configuration\nPROJECT_ID = os.environ.get(\"GOOGLE_CLOUD_PROJECT\", \"your-gcp-project-id\") # e.g., \"my-project-123\"\nINSTANCE_ID = os.environ.get(\"BIGTABLE_INSTANCE_ID\", \"your-bigtable-instance-id\") # e.g., \"my-instance\"\nTABLE_ID = os.environ.get(\"BIGTABLE_TABLE_ID\", \"your-table-id\") # e.g., \"my-table\"\nCOLUMN_FAMILY_ID = \"cf1\"\nCOLUMN_QUALIFIER = \"greeting\"\nROW_KEY = \"r1\"\n\n# Initialize Bigtable client\n# Ensure GOOGLE_APPLICATION_CREDENTIALS environment variable is set for local dev\n# or gcloud auth application-default login has been run.\n# Use admin=True if you need to create/manage tables/instances.\nclient = bigtable.Client(project=PROJECT_ID, admin=True)\ninstance = client.instance(INSTANCE_ID)\n\n# Check if table exists, create if not\ntable = instance.table(TABLE_ID)\nif not table.exists():\n    print(f\"Creating table {TABLE_ID}...\")\n    table.create(column_families={COLUMN_FAMILY_ID: column_family.ColumnFamily()})\n    print(f\"Table {TABLE_ID} created.\")\nelse:\n    print(f\"Table {TABLE_ID} already exists.\")\n\n# Write a row\nprint(f\"Writing row '{ROW_KEY}'...\")\nrow_entry = row.DirectRow(ROW_KEY.encode(\"utf-8\"))\nrow_entry.set_cell(COLUMN_FAMILY_ID, COLUMN_QUALIFIER.encode(\"utf-8\"),\n                   b\"Hello Bigtable!\", timestamp=client.timestamp())\ntable.mutate_rows([row_entry])\nprint(f\"Row '{ROW_KEY}' written.\")\n\n# Read a row\nprint(f\"Reading row '{ROW_KEY}'...\")\nread_row = table.read_row(ROW_KEY.encode(\"utf-8\"))\n\nif read_row:\n    # Get the latest cell value for the specific column\n    cells = read_row.cells[COLUMN_FAMILY_ID][COLUMN_QUALIFIER.encode(\"utf-8\")]\n    latest_value = cells[0].value.decode(\"utf-8\")\n    timestamp = cells[0].timestamp\n    print(f\"Read: {COLUMN_FAMILY_ID}:{COLUMN_QUALIFIER} = '{latest_value}' (at {timestamp})\")\nelse:\n    print(f\"Row '{ROW_KEY}' not found.\")\n\n# Optional: Delete the table for cleanup\n# print(f\"Deleting table {TABLE_ID}...\")\n# table.delete()\n# print(f\"Table {TABLE_ID} deleted.\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `google-cloud-bigtable` client, create a table (if it doesn't exist), write a simple row, and then read that row back. Ensure your `GOOGLE_CLOUD_PROJECT` and `BIGTABLE_INSTANCE_ID` environment variables are set, and you have authenticated to Google Cloud (e.g., via `gcloud auth application-default login`) with appropriate permissions to manage and access Bigtable."},"warnings":[{"fix":"Upgrade your Python environment to 3.7 or newer to use current versions of the library.","message":"Python versions older than 3.7 are no longer supported by recent `google-cloud-bigtable` releases. Python 3.6 support ended with v2.10.1 (2022-06-03), and Python 2.7/3.5 support ended with v1.7.0 (2021-02-09).","severity":"breaking","affected_versions":"<=2.10.1 (for Python 3.6), <=1.7.0 (for Python 2.7, 3.5)"},{"fix":"Design your application to be fully asynchronous from the ground up to leverage the `BigtableDataClientAsync` client, or stick to the synchronous `Client` for synchronous codebases.","message":"The `BigtableDataClientAsync` client (introduced in v2.23.0) is designed for `asyncio` codebases. It is generally not recommended to use the async client within an otherwise synchronous application, as it can negate performance benefits and lead to unexpected behavior.","severity":"gotcha","affected_versions":">=2.23.0"},{"fix":"Deploy your client applications in the same zone as your Bigtable instance. Follow Bigtable schema design best practices to distribute reads and writes evenly across your table.","message":"Suboptimal performance can occur if your Bigtable client application is not running in the same Google Cloud zone as your Bigtable cluster, or if your Bigtable schema is poorly designed, leading to hot-spotting or inefficient reads/writes.","severity":"gotcha","affected_versions":"All"},{"fix":"Always check for `None` when reading a row: `if read_row: ...`. Remember to decode byte values to strings or other appropriate types when processing data.","message":"The `table.read_row()` method returns `None` if a row with the specified key does not exist. Cell values are returned as bytes and require explicit decoding (e.g., `.decode(\"utf-8\")`) for string representation.","severity":"gotcha","affected_versions":"All"},{"fix":"Utilize `from google.cloud import bigtable` and its API directly for optimal performance and access to the latest Bigtable features, unless strict Apache HBase API compatibility is a requirement.","message":"For new projects, prefer using the native `google-cloud-bigtable` client directly over wrapper libraries like `google-cloud-happybase` (which mimics the Apache HBase API). The native client provides more direct access to Bigtable features and better performance due to avoiding object conversion overhead.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your environment is correctly authenticated. For local development, run `gcloud auth application-default login`. For production environments, use service accounts with appropriate roles, set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to point to a service account key file, or ensure your compute instance has the necessary scopes enabled.","message":"The application failed to find Google Cloud credentials. This typically happens when running in an environment where Application Default Credentials (ADC) are not set up or accessible. Common causes include running locally without 'gcloud auth application-default login', missing environment variables (GOOGLE_APPLICATION_CREDENTIALS), or incorrect IAM permissions on the executing service account/VM.","severity":"breaking","affected_versions":"All"},{"fix":"Ensure that your environment is properly authenticated. This typically involves setting `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file path, running `gcloud auth application-default login` for user credentials, or deploying in an environment with managed identities (e.g., GCE, GKE, Cloud Run, App Engine) that provide service account credentials by default. Refer to the Google Cloud authentication documentation for details on setting up Application Default Credentials.","message":"The `google-cloud-bigtable` client library requires appropriate Google Cloud credentials to authenticate and authorize API requests. If credentials are not explicitly provided, the library will attempt to use Application Default Credentials (ADC), which may fail if not configured in the execution environment.","severity":"breaking","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-05-12T14:16:15.020Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install google-cloud-bigtable`. If using a virtual environment, ensure it is activated.","cause":"The `google-cloud-bigtable` library is not installed in the Python environment, or the environment where the code is being run does not have access to the installed package.","error":"ModuleNotFoundError: No module named 'google.cloud.bigtable'"},{"fix":"Ensure the service account or user has the appropriate Bigtable IAM roles (e.g., `roles/bigtable.user`, `roles/bigtable.reader`, `roles/bigtable.admin`) on the Bigtable instance or project. Verify Application Default Credentials are correctly configured if running locally.","cause":"The service account or user attempting to access Bigtable does not have the necessary Identity and Access Management (IAM) permissions for the requested operation or resource. This could also manifest as 'Missing IAM permission: bigtable.instances.ping'.","error":"google.api_core.exceptions.PermissionDenied: 7 PERMISSION_DENIED: Request had insufficient authentication scopes."},{"fix":"Optimize your Bigtable schema for even data distribution, batch mutations, ensure the client application is in the same geographical region as the Bigtable instance, scale up the Bigtable cluster if overloaded, or increase the operation timeout in the client configuration if appropriate for the workload.","cause":"A Bigtable operation, such as reading or writing a large amount of data or performing a complex scan, took longer than the default or configured timeout. This can be caused by network latency, an overloaded Bigtable cluster, or inefficient schema design leading to hotspotting.","error":"google.api_core.exceptions.DeadlineExceeded: The deadline expired before the operation could complete."},{"fix":"Verify that the Bigtable instance, table, and column family IDs in your code are correct and that the resources exist in your Google Cloud project. Ensure there are no typos and that the client is pointing to the correct project and instance.","cause":"The specified Bigtable instance, table, or column family ID does not exist, or the client is attempting to access a resource that has been deleted or has not yet been created.","error":"google.api_core.exceptions.NotFound: 404 Not found: Table <table_id>"},{"fix":"Add logic to check for the resource's existence (e.g., `client.instance(instance_id).table(table_id).exists()`) before attempting to create it, or implement exception handling to gracefully manage `AlreadyExists` errors if idempotent creation is desired.","cause":"The code is attempting to create a Bigtable resource (e.g., a table) that already exists in the specified instance.","error":"google.api_core.exceptions.AlreadyExists: 6 ALREADY_EXISTS: The entity that a client attempted to create already exists."}],"ecosystem":"pypi","meta_description":null,"install_score":95,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.54,"mem_mb":35.8,"disk_size":"73.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.15,"mem_mb":26.2,"disk_size":"72M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.23,"mem_mb":37.9,"disk_size":"79.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.84,"mem_mb":29.1,"disk_size":"77M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3.16,"mem_mb":37.5,"disk_size":"70.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.17,"mem_mb":28.8,"disk_size":"69M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":3,"mem_mb":38.3,"disk_size":"70.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.25,"mem_mb":29.4,"disk_size":"68M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.35,"mem_mb":36,"disk_size":"74.1M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.33,"mem_mb":26.5,"disk_size":"72M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","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}]}}