Install & Compatibility
Where this runs
tested against v0.15.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 508.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 21.1s · import 0.000s · 458MB
489MB installed
● package 489MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
bigquery_magics
✓ %load_ext bigquery_magics
Magics are loaded using the %load_ext command, not Python's 'import' statement.
This quickstart demonstrates how to load the `bigquery_magics` extension, set the Google Cloud project, and execute a BigQuery SQL query directly within a Jupyter cell. The `%%bigquery` cell magic runs the query and automatically saves the results into a pandas DataFrame, specified as a line argument.
# Load the BigQuery magics extension
%load_ext bigquery_magics
# Set your Google Cloud Project ID
# Replace 'your-gcp-project-id' with your actual Project ID.
# Ensure your environment is authenticated (e.g., via gcloud auth application-default login)
import os
os.environ['GOOGLE_CLOUD_PROJECT'] = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')
# Run a BigQuery SQL query using the %%bigquery cell magic
# The results will be stored in a pandas DataFrame named 'df_names'
%%bigquery df_names
SELECT
name,
SUM(number) AS count
FROM
`bigquery-public-data.usa_names.usa_1910_current`
GROUP BY
name
ORDER BY
count DESC
LIMIT
5;
# Display the DataFrame
print(df_names)
Debug
Known issues
breakingPython 2 and older Python 3 versions (<= 3.8) are no longer supported. Ensure your environment runs Python 3.9 or newer.fixUpgrade your Python environment to 3.9 or higher. The current version requires Python >= 3.10.
affects: <=0.10.x
gotchaAuthentication to Google Cloud and BigQuery is crucial. Without proper Application Default Credentials (ADC) or explicit credential setup, queries will fail with authorization errors.fixEnsure you have authenticated your environment using `gcloud auth application-default login` for local development, or that your service account has the necessary IAM permissions (e.g., BigQuery User, BigQuery Data Editor) if running on Google Cloud.
affects: All versions
gotchaSpecifying the correct Google Cloud Project ID is essential. If not explicitly set via an environment variable or magic argument, the magic may fail or query against an unintended project.fixSet the `GOOGLE_CLOUD_PROJECT` environment variable, or use the `--project` argument with the `%%bigquery` magic (e.g., `%%bigquery --project your-project-id`). Ensure billing is enabled for the specified project.
affects: All versions
gotchaThe `bigquery-magics` library's source code was migrated into the larger `googleapis/google-cloud-python` monorepo. While generally not a breaking change for users, be aware that issue tracking and contribution guidelines are now centralized in the monorepo.fixRefer to the monorepo's documentation for the most up-to-date development and contribution information.
affects: All versions (organizational change)
Upgrade
Version history
0.15.0latest on PyPI · released May 7, 2026
Audit
Dependencies
google-cloud-bigqueryrequiredCore library for interacting with the BigQuery API.
pandasrequiredQuery results are returned as pandas DataFrames by default.
google-cloud-bigquery-storagerequiredRequired by google-cloud-bigquery (>=3.x) for faster result downloads.
pyarrowrequiredRequired by google-cloud-bigquery (>=3.x) for efficient data handling, especially with storage API.
tqdmoptionalOptional dependency for displaying query progress bars.