Install & Compatibility
Where this runs
tested against v1.7.1 · 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 0.000s · 349.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 9.4s · import 0.000s · 312MB
332MB installed
● package 332MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
db_dtypes
✓ import db_dtypes # noqa: F401
Importing the module registers the extension dtypes with pandas. The '# noqa: F401' is often added to suppress 'unused import' warnings as the import's primary purpose is side-effect registration.
DateDtype
✓ from db_dtypes import DateDtype
✗ import db_dtypes.DateDtype
While 'import db_dtypes' registers all, explicit import is for direct reference, e.g., in `pd.Series(dtype=DateDtype())`.
TimeDtype
✓ from db_dtypes import TimeDtype
JSONDtype
✓ from db_dtypes import JSONDtype
This quickstart demonstrates how to initialize pandas Series with custom `dbdate`, `dbtime`, and `dbjson` dtypes provided by the `db-dtypes` library. The initial `import db_dtypes` is crucial for registering these extension types with pandas.
import datetime
import pandas as pd
import db_dtypes # noqa: F401
# Using dbdate dtype
dates = pd.Series([datetime.date(2023, 1, 1), '2023-01-02'], dtype='dbdate')
print('Dates Series:')
print(dates)
# Using dbtime dtype
times = pd.Series([datetime.time(10, 30, 0), '15:45:00.123'], dtype='dbtime')
print('\nTimes Series:')
print(times)
# Using dbjson dtype
json_data = pd.Series([{'key': 'value'}, [1, 2, 3], 'null'], dtype='dbjson')
print('\nJSON Series:')
print(json_data)
Debug
Known issues
breakingPython 2 support was dropped as of January 1, 2020. The library currently requires Python >= 3.9. Older versions of the library (1.4.3 onwards) also explicitly dropped support for Python 3.7 and 3.8.fixEnsure your environment uses Python 3.9 or newer.
affects: <= 1.4.2 (for Python < 3.9); < 1.4.3 (for Python 3.7, 3.8)
breakingWith `google-cloud-bigquery` version 3.0.0, `db-dtypes` became a required dependency for the `pandas` extra. BigQuery's `DATE` and `TIME` data types now map directly to `dbdate` and `dbtime` dtypes, and the `date_as_object` parameter was removed.fixUpdate `google-cloud-bigquery` to a compatible version and ensure `db-dtypes` is installed. Remove `date_as_object` parameter if previously used.
affects: google-cloud-bigquery >= 3.0.0
gotchaFor `db-dtypes` extension types (like `dbdate`, `dbtime`, `dbjson`) to be recognized by pandas, the `db_dtypes` module must be imported at least once. This import performs the necessary registration of the custom dtypes.fixAlways include `import db_dtypes` at the beginning of your script or session. It's often accompanied by `# noqa: F401` to prevent linting warnings about unused imports.
affects: All
gotchaWhen converting BigQuery `DATE` data to pandas `dbdate` dtype, any date values falling outside the range of `pandas.Timestamp.min` (1677-09-22) and `pandas.Timestamp.max` (2262-04-11) will map to the generic `object` dtype in pandas instead of `dbdate`.fixBe aware of the valid date range when processing historical or futuristic date data from BigQuery that uses the `dbdate` dtype, and handle `object` dtype columns appropriately if out-of-bounds dates are expected.
affects: All
gotchaStandard Pandas `float64` can introduce precision errors when dealing with database `DECIMAL` or `NUMERIC` types. While `db-dtypes` aims to improve type fidelity, there isn't a direct `DecimalDtype` class for explicit import like `DateDtype`.fixRely on the integration with BigQuery connectors (e.g., `google-cloud-bigquery`) to handle `DECIMAL` types. If working with generic SQL and Pandas, consider explicit conversion to Python's `decimal.Decimal` objects or using other libraries that provide exact decimal dtypes.
affects: All
Errors
Common errors & fixes
ValueError: Please install the 'db-dtypes' package to use this function.
This error occurs when a function, often within a dependent library like `google-cloud-bigquery` or `pandas-gbq`, requires the `db-dtypes` package but it is either not installed, not installed in the active Python environment, or is an outdated version.
fixInstall or upgrade the `db-dtypes` package using pip: `pip install --upgrade db-dtypes`. If using `google-cloud-bigquery`, installing with the pandas extra (`pip install 'google-cloud-bigquery[pandas]'`) can also ensure `db-dtypes` is present.
pip install db dtypes
This is not an error message but a common incorrect command that leads to installation problems because the package name `db-dtypes` contains a hyphen, which is omitted in this command. Python's `pip` interprets 'db' and 'dtypes' as two separate packages.
fixUse the correct package name with a hyphen: `pip install db-dtypes`.
AttributeError: module 'numpy' has no attribute 'dtypes'
This `AttributeError` typically arises from an incompatibility between `db-dtypes` (or a library that depends on it, such as `bigframes`) and the installed version of `numpy`, where a required `numpy` attribute or function is missing or has been renamed in the current `numpy` version.
fixEnsure `numpy` and `db-dtypes` are compatible. It's often resolved by updating both packages: `pip install --upgrade numpy db-dtypes`. Check the documentation for specific version requirements if the issue persists.
Unexpected Pandas dtype after loading from DB (e.g., float64 instead of DecimalDtype) or Data precision loss
Pandas' default type inference may convert database-specific types (like BigQuery's `DECIMAL` or `NUMERIC`) to standard Pandas dtypes (e.g., `float64`), which can lead to precision loss or incorrect data representation if `db-dtypes` extension types are not explicitly used.
fixExplicitly specify `db-dtypes` extension types when loading data using the `dtype` parameter in Pandas functions (e.g., `pd.read_sql(..., dtype={'my_decimal_col': 'db_decimal'})`) or by converting the column type after loading (`df['my_decimal_col'] = df['my_decimal_col'].astype('db_decimal')`). Also, ensure `import db_dtypes # noqa` is in your code to register the extension dtypes. Upgrade
Version history
1.7.1latest on PyPI · released Jul 8, 2026
Audit
Dependencies
pandasrequiredProvides the DataFrame and Series structures that db-dtypes extends with custom data types.
pyarrowrequiredEnhances performance for reading and writing data, especially with BigQuery, by leveraging the Apache Arrow format.
numpyrequiredUnderlying dependency for pandas and array operations.