Registry / gcp / pandas-gbq

pandas-gbq

JSON →
library0.34.1pypypi✓ verified 50d ago

pandas-gbq is a Python library that provides a convenient interface to connect pandas DataFrames with Google BigQuery. It simplifies reading data from BigQuery into a pandas.DataFrame and writing DataFrames to BigQuery tables. The current version is 0.34.1, released on 2026-03-26, and the library maintains a regular release cadence, typically with monthly or bi-monthly updates for new features and bug fixes.

gcpdatadatabase
pip install pandas-gbq
Install & Compatibility
Where this runs
tested against v0.35.0 · 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
py 3.103.925 runs
installs and imports cleanly · install 0.0s · import 3.346s · 396.7MB
glibc
py 3.103.925 runs
installs and imports cleanly · install 15.1s · import 2.821s · 362MB
391MB installed
● package 391MB
Code
Verified usage

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

read_gbq
from pandas_gbq import read_gbq
import pandas_gbq
Context
from pandas_gbq import Context
import pandas_gbq
query
from pandas_gbq import query
import pandas_gbq

This quickstart demonstrates how to read data from a public BigQuery dataset into a pandas DataFrame and write a pandas DataFrame to a new BigQuery table. It assumes you have a Google Cloud project set up and have authenticated (e.g., using `gcloud auth application-default login`). The `project_id` is retrieved from the `GOOGLE_CLOUD_PROJECT` environment variable for robustness.

import os import pandas as pd import pandas_gbq # Set your Google Cloud Project ID # It's recommended to set this as an environment variable or via credentials project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id') # --- Reading data from BigQuery --- # Example query from a public dataset sql_query = """ SELECT country_name, alpha_2_code FROM `bigquery-public-data.utility_us.country_code_iso` WHERE alpha_2_code LIKE 'U%' LIMIT 5 """ try: df_read = pandas_gbq.read_gbq(sql_query, project_id=project_id) print("\n--- Data read from BigQuery ---") print(df_read) except Exception as e: print(f"Error reading from BigQuery: {e}") print("Please ensure GOOGLE_CLOUD_PROJECT is set and you have authenticated (e.g., `gcloud auth application-default login`).") # --- Writing data to BigQuery --- # Create a sample DataFrame to upload data = { 'col1': [1, 2, 3], 'col2': ['A', 'B', 'C'], 'timestamp_col': pd.to_datetime(['2026-01-01', '2026-01-02', '2026-01-03']) } df_write = pd.DataFrame(data) # Define destination table (dataset.tablename) destination_table = 'my_test_dataset.my_test_table' # To avoid errors, you might want to replace the table if it exists for testing # In production, consider 'append' or 'fail' with proper checks try: pandas_gbq.to_gbq( df_write, destination_table, project_id=project_id, if_exists='replace' # Options: 'fail', 'replace', 'append' ) print(f"\n--- DataFrame successfully written to {destination_table} in project {project_id} ---") except Exception as e: print(f"Error writing to BigQuery: {e}") print("Ensure 'my_test_dataset' exists in BigQuery or remove 'my_test_dataset.' from 'destination_table' to allow automatic dataset creation if permitted.")
Debug
Known issues
breakingPython 2 support was officially dropped as of January 1, 2020. Versions released after this date require Python 3.9 or higher.
fix
Upgrade to Python 3.9+ and ensure all project dependencies are compatible.
affects: 0.20.0 and later
gotchaAuthentication is critical. Without proper credentials or a `project_id`, `pandas-gbq` will raise errors (e.g., `ValueError: Could not determine project ID`). Common authentication methods include Application Default Credentials (ADC), service account keys, or user-based OAuth.
fix
Set the `GOOGLE_CLOUD_PROJECT` environment variable. Authenticate using `gcloud auth application-default login`, provide a service account JSON file via the `credentials` parameter, or set `pandas_gbq.context.credentials` and `pandas_gbq.context.project` explicitly.
affects: All versions
breakingThe `to_gbq` function has breaking changes in how it infers BigQuery data types for certain pandas dtypes. Naive (timezone-unaware) datetime columns are now loaded as BigQuery `DATETIME` instead of `TIMESTAMP`. Object columns containing boolean or dictionary values are loaded as `BOOLEAN` or `STRUCT` respectively, instead of `STRING`. `UInt8` columns are now `INT64`.
fix
Review and update BigQuery table schemas if necessary. For `datetime` columns, consider making them timezone-aware (`pd.to_datetime(..., utc=True)`) if `TIMESTAMP` is desired, or explicitly define `table_schema` in `to_gbq`.
affects: 0.34.0 and later
gotchaWhen using `to_gbq`, the default `if_exists` parameter is 'fail', meaning the operation will fail if the destination table already exists.
fix
Explicitly set `if_exists='replace'` to overwrite the table, or `if_exists='append'` to add data to an existing table. Always handle this parameter carefully to prevent unintended data loss or duplication.
affects: All versions
deprecatedThe `auth_local_webserver` parameter's default behavior changed from `False` to `True` in `pandas-gbq` version 1.5.0. This is due to Google deprecating the 'out-of-band' (copy-paste) authentication flow.
fix
Ensure your environment allows for the local webserver flow (e.g., a browser can open `localhost:808X`). If working in a headless environment, consider using service account authentication.
affects: 1.5.0 and later
Upgrade
Version history
0.35.0latest on PyPI
Audit
Dependencies
pandasrequiredCore DataFrame manipulation library.
google-cloud-bigqueryrequiredGoogle Cloud client library for BigQuery API interactions.
google-authrequiredAuthentication and authorization for Google's APIs.
pydata-google-authrequiredHelpers for user-based authentication to Google's API.
pyarrowoptionalUsed for efficient data formatting and transfer, especially with the BigQuery Storage API.
google-cloud-bigquery-storageoptionalClient library for the BigQuery Storage API, enabling faster large data downloads.
tqdmoptionalProvides progress bars for data uploads/downloads.
Agent activity
87 hits · last 30 days
node
16
seranking-bot
4
ahrefsbot
3
Meta
1
bytedance
1
Resources