Pandas Data Types for SQL Systems

1.5.0 verified Tue May 12 auth: no python install: verified quickstart: verified

db-dtypes is a specialized Python library that provides Pandas Extension Dtypes to represent and interact with data types commonly found in relational databases, particularly BigQuery and Spanner. It aims to ensure data integrity and improve performance by providing faithful representations of types like Date, Time, and JSON. The library is actively maintained by Google, with multiple releases per year, and its current version is 1.5.0.

pip install db-dtypes

Common errors

error ValueError: Please install the 'db-dtypes' package to use this function. ↓

cause 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.

fix

Install 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.

error pip install db dtypes ↓

cause 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.

fix

Use the correct package name with a hyphen: pip install db-dtypes.

error AttributeError: module 'numpy' has no attribute 'dtypes' ↓

cause 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.

fix

Ensure 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.

error Unexpected Pandas dtype after loading from DB (e.g., float64 instead of DecimalDtype) or Data precision loss ↓

cause 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.

fix

Explicitly 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.

Warnings

breaking Python 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. ↓

fix Ensure your environment uses Python 3.9 or newer.

breaking With `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. ↓

fix Update `google-cloud-bigquery` to a compatible version and ensure `db-dtypes` is installed. Remove `date_as_object` parameter if previously used.

gotcha For `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. ↓

fix Always 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.

gotcha When 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`. ↓

fix Be 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.

gotcha Standard 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`. ↓

fix Rely 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.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - - 340.3M

3.10 alpine (musl) - - - 334.9M

3.10 slim (glibc) wheel 10.1s - 309M

3.10 slim (glibc) - - - 304M

3.11 alpine (musl) wheel - - 364.3M

3.11 alpine (musl) - - - 358.7M

3.11 slim (glibc) wheel 9.1s - 332M

3.11 slim (glibc) - - - 328M

3.12 alpine (musl) wheel - - 348.8M

3.12 alpine (musl) - - - 343.2M

3.12 slim (glibc) wheel 9.8s - 316M

3.12 slim (glibc) - - - 312M

3.13 alpine (musl) wheel - - 347.9M

3.13 alpine (musl) - - - 342.3M

3.13 slim (glibc) wheel 9.9s - 315M

3.13 slim (glibc) - - - 311M

3.9 alpine (musl) wheel - - 329.4M

3.9 alpine (musl) - - - 329.2M

3.9 slim (glibc) wheel 11.0s - 307M

3.9 slim (glibc) - - - 306M

Imports

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
wrong
```
import db_dtypes.DateDtype
```
correct
```
from db_dtypes import 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
```

Quickstart verified last tested: 2026-04-24

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)