dbt Packages: Importing Reusable Modules Into Your Project

Somewhere between “write a macro for it” and “surely someone has already solved this” lies a genuinely large ecosystem of dbt packages — pre-built collections of macros, models, and tests that you can install into your own project the way you’d install a library in any other language. Before writing a generic-purpose macro from scratch, it’s worth checking whether a package already does it, tested against thousands of other projects.

What a Package Actually Is

A dbt package is just another dbt project, structured so it can be imported into yours. It typically contributes macros, and sometimes models or tests, that become available in your project as if you’d written them yourself.

Installing a Package

Packages are declared in a packages.yml file at your project root, then installed with a dedicated command.

packages:
  - package: dbt-labs/dbt_utils
    version: [">=1.1.0", "<2.0.0"]
  - package: calogica/dbt_expectations
    version: [">=0.10.0", "<0.11.0"]

dbt deps

dbt deps downloads each package into a dbt_packages/ directory locally. That directory should be gitignored — packages are a dependency, not something you commit to your own repo, the same way you wouldn’t commit node_modules.

dbt_packages/

Using Macros From an Installed Package

Once installed, a package’s macros are called with the package name as a namespace prefix.

select
  {{ dbt_utils.generate_surrogate_key(['customer_id', 'order_date']) }} as order_key,
  customer_id,
  order_date,
  amount
from {{ ref('stg_orders') }}

This calls generate_surrogate_key from the dbt_utils package exactly like calling any macro you’d written yourself — the only difference is the dbt_utils. prefix identifying which package it comes from.

Version Pinning and Why It Matters

The version range in packages.yml isn’t a formality — packages do introduce breaking changes between major versions, and an unpinned or overly loose range means a dbt deps run six months from now could silently pull in a version that changes macro behavior underneath you.

packages:
  # Loose — risky, could pull in breaking changes unexpectedly
  - package: dbt-labs/dbt_utils
    version: ">=1.0.0"

  # Pinned to a compatible range — the safer default
  - package: dbt-labs/dbt_utils
    version: [">=1.1.0", "<2.0.0"]

Treat package versions the same way you’d treat dependency versions in any other software project — pin them, and upgrade deliberately with a changelog review, not implicitly on every dbt deps run.

Installing From Git, Not Just the Package Hub

Not every useful package is published to dbt’s public Package Hub. Private, internal, or unpublished packages can be installed directly from a Git repository.

packages:
  - git: "https://github.com/your-org/internal-dbt-macros.git"
    revision: v2.3.0

Pinning to a specific tag or commit (revision) matters even more here than with published packages, since there’s no registry enforcing semantic versioning discipline on an internal repo.

Building an Internal Package for Your Own Organization

Once a set of macros is genuinely reusable across multiple dbt projects within your company — not just multiple models within one project — it’s worth extracting them into their own internal package rather than copy-pasting macro files between repos.

internal-dbt-macros/
  dbt_project.yml
  macros/
    generate_surrogate_key.sql
    standard_grants.sql
    custom_tests/
      not_null_proportion.sql

Any other project in the organization can then install this exactly like a public package, keeping shared conventions in one maintained place instead of drifting apart across teams’ individual projects.

Packages vs. Writing Your Own Macro

The decision isn’t always obvious. A useful heuristic:

Writing a macro that duplicates something dbt_utils already provides, tested and maintained by a large community, is rarely a good use of time compared to just installing the package.

Upgrading a Package Deliberately

When a genuinely new package version is worth adopting — a bug fix, a new macro you actually need — the safe upgrade path is a dedicated branch, not a routine dbt deps that happens to pull a newer version silently.

# Before
packages:
  - package: dbt-labs/dbt_utils
    version: [">=1.1.0", "<1.2.0"]

# After, on its own branch, reviewed like any other dependency bump
packages:
  - package: dbt-labs/dbt_utils
    version: [">=1.2.0", "<1.3.0"]

dbt deps
dbt build

Running the full build after a version bump, before merging, catches any breaking macro signature changes immediately — treating this exactly like upgrading any other software dependency, rather than assuming package updates are always safe by default.

Common Mistakes

Committing dbt_packages/ to version control. This bloats your repo with third-party code that should be fetched fresh via dbt deps, not tracked — always gitignore it.

Forgetting to run dbt deps after adding a package. Editing packages.yml alone doesn’t install anything; it just declares intent. dbt deps is a separate, required step, and CI pipelines need to run it before any dbt run or dbt test.

Unpinned version ranges causing silent breakage. A wide-open version constraint means a routine dbt deps months later can pull in a major version bump with different macro signatures, breaking models that were working fine yesterday.

Summary

Packages are how the dbt ecosystem avoids everyone reinventing the same surrogate-key macro. Before writing something generic from scratch, check whether dbt_utils — covered next in dbt_utils Package — already solves it.