dbt Packages: Using and Creating Shareable dbt Components

dbt packages are shareable collections of macros, models, tests, and seeds installed into a dbt project from dbt Hub (packages.getdbt.com) or from a GitHub repository. They are dbt's dependency management system — instead of every project reimplementing the same surrogate key generation, date spine, or data type conversion logic, packages distribute these as reusable components.

This guide covers the most useful community packages, how to install and configure them, and how to create your own internal package.

Installing packages

Packages are declared in packages.yml in the dbt project root:

The dbt_utils entry installs the dbt_utils package at version 1.3.0 from dbt Hub. A git entry installs from a GitHub repository — useful for internal packages hosted privately. After updating packages.yml, run dbt deps to install.

Installed packages live in the dbt_packages/ directory. Add dbt_packages/ to .gitignore — it is a build artifact, not source code.

The essential community packages

**dbt_utils (dbt-labs/dbt_utils)**: The most widely used dbt package. Provides:

- generate_surrogate_key([col1, col2]): Hash-based surrogate key from multiple columns

- date_spine(datepart, start_date, end_date): Generates one row per date in a range

- star(from=ref('model'), except=['col1']): SELECT all columns except specified ones

- union_relations([ref('a'), ref('b'), ...]: UNION ALL with schema alignment

- get_column_values(table, column): Returns distinct column values as a list

- pivot and unpivot: Dynamic pivoting without hard-coding column names

**dbt_expectations (calogica/dbt_expectations)**: Brings Great Expectations-style test types to dbt:

- expect_column_values_to_be_between

- expect_column_quantile_values_to_be_between

- expect_column_mean_to_be_between

- expect_table_row_count_to_be_between

- expect_column_distinct_count_to_equal

- expect_column_values_to_match_regex

These fill the gap between dbt's four built-in generic tests and the richer statistical validation that production data models need.

**dbt_date (calogica/dbt_date)**: Date and time utility macros and models, including a configurable date spine generator and date part extraction macros that work across multiple warehouse adapters.

**codegen (dbt-labs/codegen)**: Generates boilerplate dbt YAML from introspecting the database — generates source yaml from database tables, generates model yaml from existing models. Dramatically speeds up the process of adding documentation to existing models.

**dbt_project_evaluator (dbt-labs/dbt_project_evaluator)**: Audits a dbt project for best practices compliance — models without tests, models without documentation, sources without freshness checks, direct references to source tables from mart models. Run dbt build --select package:dbt_project_evaluator to get a compliance report.

**audit_helper (dbt-labs/audit_helper)**: Provides macros for comparing query results between environments or between versions of a model — useful for validating that a refactor produces the same results as the original model.

Using packages in your project

Reference package macros with the package namespace: dbt_utils.generate_surrogate_key(['order_id', 'line_item_id']). The namespace prevents collisions between packages and your own macros.

Package tests are added to schema.yml the same way as built-in tests: list them under the tests key on a column definition. Package models (when the package includes models, like dbt_project_evaluator) appear in the dbt_packages/ schema.

Version pinning

Always pin packages to specific versions in packages.yml. Unpinned packages (version: ">0.1.0") will upgrade automatically when you run dbt deps, potentially introducing breaking changes. Pin to exact versions: version: 1.3.0. Upgrade intentionally after reviewing the package's changelog.

Creating an internal package

For organisations with multiple dbt projects that share macros, models, or tests, an internal package centralises the shared logic. Create a new repository with a dbt project structure (dbt_project.yml, macros/, models/, tests/) containing only the shared components.

Reference the internal package in each project's packages.yml using a git entry pointing to the private repository:

The revision can be a tag, branch name, or commit hash. Pin to tags for stability.

Internal package contents typically include:

- Custom generic tests shared across projects (e.g., custom not_negative test, composite not_null test)

- Shared macros for surrogate key generation, null-safe comparisons, or environment-specific logic

- Shared staging models for source systems that multiple projects use

- Shared seed files (currency codes, country codes, shared reference data)

The internal package is versioned independently. When you update the package, projects that pin to a specific tag are unaffected until they explicitly upgrade.

Package maintenance

Community packages are maintained by their authors with varying levels of active maintenance. Before adopting a package:

- Check the GitHub repository's recent activity (last commit, open issues, release cadence)

- Verify compatibility with your dbt version and warehouse adapter

- Check whether the package has known issues that affect your use case

For critical functionality (surrogate key generation, date spine), the dbt-labs packages have stable long-term maintenance backing. Community packages with low activity may not receive adapter updates when new warehouse versions ship.

For the broader dbt context, see dbt best practices, dbt macros guide, and dbt project structure. Our data architecture consulting practice designs and builds production dbt environments — book a free review to discuss your dbt project requirements.

A former Microsoft data architect audits your data foundation, identifies your top priorities, and sends you a written plan. Free. No pitch.