Install & Compatibility
Where this runs
tested against v1.11.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
py 3.10
✕ build_error
✓ 26.3s
py 3.11
✕ build_error
✓ 21.4s
py 3.12
✕ build_error
✓ 20.8s
py 3.13
✕ build_error
✕ build_error
176MB installed
● package 176MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
dbt-athena
✓ dbt-athena is used via the dbt CLI and profiles.yml configuration; no direct Python imports for end-user functionality are typically needed.
dbt adapters primarily extend dbt CLI functionality and provide connection configuration, rather than direct Python APIs for common use cases.
This quickstart outlines the steps to set up a dbt project with the dbt-athena adapter. It involves installing the necessary packages, initializing a dbt project, configuring your AWS Athena connection details in `profiles.yml`, and then running `dbt` commands to test and execute your models. Ensure you have an S3 bucket for query results and an Athena database set up in AWS.
# 1. Install dbt-athena and dbt-core
pip install dbt-core dbt-athena
# 2. Initialize a new dbt project (follow prompts, select 'athena' as database type)
dbt init my_athena_project
# 3. Configure your profiles.yml (e.g., ~/.dbt/profiles.yml or project_root/profiles.yml)
# Example profiles.yml content:
# my_athena_project:
# target: dev
# outputs:
# dev:
# type: athena
# s3_staging_dir: s3://your-athena-query-results-bucket/dbt-staging/
# region_name: us-east-1
# database: your_athena_database
# schema: dbt_schema
# threads: 4
# aws_profile_name: default # Or use aws_access_key_id and aws_secret_access_key
# 4. Create an S3 bucket and Athena database as prerequisites
# (AWS CLI/Console steps, not Python code):
# aws s3 mb s3://your-athena-query-results-bucket
# aws athena create-data-catalog --name your_athena_database --type LAMBDA --parameters "catalog-id"="your_glue_catalog_id" # Or simply use an existing database
# 5. Create a sample dbt model (e.g., my_athena_project/models/my_first_model.sql)
# -- my_athena_project/models/my_first_model.sql
# select 1 as id, 'hello' as message
# 6. Test the connection and run your dbt project
dbt debug --target dev
dbt run --target dev
dbt --version
Debug
Known issues
breakingAs of dbt-core version 1.8, dbt-athena (and other adapters) no longer automatically install `dbt-core`. You must install `dbt-core` separately and ensure compatibility with your adapter version.fixExplicitly install `dbt-core` alongside `dbt-athena`: `pip install dbt-core dbt-athena`.
affects: dbt-athena >= 1.8.0
gotchaThe `dbt-athena-community` package is now a wrapper around `dbt-athena`. While still functional for backward compatibility, new projects and migrations should directly use `dbt-athena`.fixPrefer `pip install dbt-athena` for new installations and when upgrading.
affects: All versions where `dbt-athena` exists alongside `dbt-athena-community`.
gotchaIf a dbt model has the same name as an existing table in the AWS Glue catalog, or if a model is configured to use the same S3 location as an existing table, the adapter *deletes* files in that table's S3 location before recreating the table. This is to avoid conflicts.fixEnsure `s3_staging_dir` and `s3_data_dir` configurations are carefully managed to prevent unintended data loss. Use distinct locations for different models or projects if data needs to be preserved outside of dbt's management.
affects: All versions
gotchaThe `num_retries` parameter in `profiles.yml` (e.g., for query retries) is often misunderstood. Setting `num_retries: N` results in `N-1` actual retries after the initial attempt. For one retry, you should set `num_retries: 2`.fixSet `num_retries` to `N+1` to achieve `N` retries (i.e., `num_retries: 2` for one retry).
affects: All versions
gotchaAthena SQL (used by dbt-athena for most operations) imposes a limit of 100 partitions per write operation. This can cause issues with full table rebuilds or large incremental merges on highly partitioned tables.fixFor tables exceeding this limit during writes, consider batching operations or utilizing Athena Spark for Python models, which can handle larger partition counts. This limit does not apply to Athena Spark.
affects: All versions
gotchaTable, schema, and database names should be lowercase when using dbt-athena to avoid potential conflicts and issues with Athena's case-insensitivity behavior.fixStandardize all dbt model, schema, and database names to lowercase in your project and configurations.
affects: All versions
Upgrade
Version history
1.11.0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
dbt-corerequiredRequired as of dbt-core v1.8; adapters no longer bundle dbt-core.
boto3requiredUnderlying AWS SDK used for interacting with Athena and S3.