dbt-bouncer logo

dbt-bouncer

Configure and enforce conventions for your dbt project.

Documentation

All documentation can be found on dbt-bouncer documentation website.

Aims

dbt-bouncer aims to:

Provide a 100% configurable way to enforce conventions in a dbt project.
Be as fast as possible, running checks against dbt artifacts.
Be as easy as possible to use, with a simple config file written in YAML or TOML.
Be as flexible as possible, allowing checks to be written in Python.
Provide immediate feedback when run as a pre-commit hook or as part of a CI pipeline.

Features

Presets — start with a bundled minimal, standard or strict config, with no config file to write. Run dbt-bouncer run --preset strict.
Baselines — adopt strict checks on an existing project and fail only on new failures. Record today's failures with dbt-bouncer baseline, or compare against a previous set of artifacts with dbt-bouncer run --state ./base-target.
Discovery — browse every check with dbt-bouncer list, read one check in detail with dbt-bouncer explain check_model_names, or open the dashboard with dbt-bouncer studio.
Config linting — catch mistakes in your config before a run with dbt-bouncer validate.
AI agent integration — expose dbt-bouncer to Claude Code, Cursor and other agents over the Model Context Protocol with dbt-bouncer mcp.
CI-friendly output — write results as csv, gitlab, json, junit, sarif or tap, and get distinct exit codes for check failures, config errors and artifact errors.
Configuration anywhere — set every run option in the config file, on the command line, or through a DBT_BOUNCER_* environment variable.

See the CLI reference for all subcommands and options.

TLDR

Install dbt-bouncer:
```
pip install dbt-bouncer
```
dbt-bouncer requires a manifest.json file. If not already present, run:
```
dbt parse
```
Create a dbt-bouncer.yml config file:
```
dbt-bouncer init
```

Run dbt-bouncer:

$ dbt-bouncer run
Running dbt-bouncer (X.X.X)...
Loaded config from dbt-bouncer.yml...
Validating conf...

            Parsed artifacts for
          'dbt_bouncer_test_project'
╭──────────────────┬─────────────────┬───────╮
│ Artifact         │ Category        │ Count │
├──────────────────┼─────────────────┼───────┤
│ manifest.json    │ Exposures       │     2 │
│                  │ Macros          │     3 │
│                  │ Nodes           │    12 │
│                  │ Seeds           │     3 │
│                  │ Semantic Models │     1 │
│                  │ Snapshots       │     2 │
│                  │ Sources         │     4 │
│                  │ Tests           │    36 │
│                  │ Unit Tests      │     3 │
│ catalog.json     │ Nodes           │    13 │
│                  │ Sources         │     0 │
│ run_results.json │ Results         │    51 │
╰──────────────────┴─────────────────┴───────╯
Assembled 463 checks, running...
Running checks... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
`dbt-bouncer` failed. Please see below for more details or run `dbt-bouncer` with the `-v` flag.
Failed checks
╭────────────────────────────────────┬────────────┬──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Check name                         │  Severity  │ Failure message                                                                                                          │
├────────────────────────────────────┼────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ check_model_names:48:orders        │   ERROR    │ Models in the staging layer should always start with "stg_". - `orders` does not match the supplied regex `^stg_`.       │
╰────────────────────────────────────┴────────────┴──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Done. SUCCESS=462 WARN=0 ERROR=1

Reporting bugs and contributing code

Want to report a bug or request a feature? Let us know and open an issue.
Want to help us build dbt-bouncer? Check out the Contributing Guide.

Code of Conduct

Everyone interacting in dbt-bouncer's codebase, issue trackers, chat rooms, and mailing lists is expected to follow the Code of Conduct.

Metadata

Release files for dbt-bouncer 4.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dbt-bouncer 4.2.0
File	Size	Uploaded
dbt_bouncer-4.2.0.tar.gz	173.7 kB	Oct 14, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for dbt-bouncer 4.2.0
File	Interpreter	ABI	Platform	Reset
dbt_bouncer-4.2.0-py3-none-any.whl 223.5 kB Oct 14, 2026	Python 3	none	any	Details

Total release size: 397.2 kB

Release files / dbt_bouncer-4.2.0.tar.gz

Download URL	dbt_bouncer-4.2.0.tar.gz
Size	173.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`599ee3c7af16695d97bfcd9da47516ef9384582b6daae1d38a5b5788b89a3f5d`
BLAKE2b-256 checksum How to use checksums	`277f589f0a3ff92586d07029813e5e5f825312efd2a795e8acdbd7064e659cc8`
Upload date	Oct 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/godatadriven/dbt-bouncer
Publishing commit: github.com/godatadriven/dbt-bouncer/tree/1e04071411d13f8e76a66cf3f19e38a8f10be5b7

Workflow

Publishing configuration: github.com/godatadriven/dbt-bouncer/blob/1e04071411d13f8e76a66cf3f19e38a8f10be5b7/.github/workflows/release_pipeline.yml
Publishing logs: github.com/godatadriven/dbt-bouncer/actions/runs/38578827992/attempts/1

Artifact

Subject: dbt_bouncer-4.2.0.tar.gz
SHA-256 checksum: 599ee3c7af16695d97bfcd9da47516ef9384582b6daae1d38a5b5788b89a3f5d Verifying attestations

Release files / dbt_bouncer-4.2.0-py3-none-any.whl

Download URL	dbt_bouncer-4.2.0-py3-none-any.whl
Size	223.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ff087a22bb1c16141c09a4ad21db0a79c691f3ba64af0637fcde41870047e6f5`
BLAKE2b-256 checksum How to use checksums	`d6691f7cd64ff2a63c9136d47712bae75f6f11ed3c1b2a82536e972cf03b391e`
Upload date	Oct 14, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/godatadriven/dbt-bouncer
Publishing commit: github.com/godatadriven/dbt-bouncer/tree/1e04071411d13f8e76a66cf3f19e38a8f10be5b7

Workflow

Publishing configuration: github.com/godatadriven/dbt-bouncer/blob/1e04071411d13f8e76a66cf3f19e38a8f10be5b7/.github/workflows/release_pipeline.yml
Publishing logs: github.com/godatadriven/dbt-bouncer/actions/runs/38578827992/attempts/1

Artifact

Subject: dbt_bouncer-4.2.0-py3-none-any.whl
SHA-256 checksum: ff087a22bb1c16141c09a4ad21db0a79c691f3ba64af0637fcde41870047e6f5 Verifying attestations