How to install dbt packages (packages.yml, dbt deps)

dbt packages are projects of macros, tests and sometimes models that you can reuse in yours. dbt_utils is the best known: generic tests, SQL helpers, pivots. You list packages in packages.yml, and dbt deps downloads them into the project.

Copy and paste

# packages.yml, next to dbt_project.yml
packages:
  - package: dbt-labs/dbt_utils
    version: [">=1.4.0", "<2.0.0"]

  - git: "https://github.com/your-org/dbt-shared-macros.git"
    revision: v1.2.0        # a tag, a branch or a commit

  - local: ../shared_macros

dbt deps

Installing dbt-labs/dbt_utils
  Installed from version 1.4.1
  Up to date!

Keep the downloaded code out of Git, and let dbt clean remove it:

# dbt_project.yml
clean-targets: [target, dbt_packages]

# .gitignore
target/
dbt_packages/
logs/

Use a package

Macros and tests from a package are called with its name as a prefix:

select {{ dbt_utils.star(ref('stg_orders'), except=['updated_at']) }}
from {{ ref('stg_orders') }}

    data_tests:
      - dbt_utils.unique_combination_of_columns:
          arguments:
            combination_of_columns: [order_id, line_number]

package-lock.yml

The first dbt deps writes package-lock.yml, with the exact version it chose:

packages:
  - name: dbt_utils
    package: dbt-labs/dbt_utils
    version: 1.4.1
sha1_hash: 12792467f594b92b80d3b31eaa4e3014de94fae4

Commit this file. On every other machine, dbt deps installs the same versions even when newer ones match the range in packages.yml. To move to newer versions on purpose:

dbt deps --upgrade

dbt deps --add-package dbt-labs/dbt_utils@1.4.1 adds a package to packages.yml and installs it in one step.

Things to know

• Run dbt deps wherever dbt runs. A fresh clone, a CI job or an Airflow worker has no dbt_packages folder until dbt deps runs. Add it before dbt build in automated jobs.
• Ranges. A range like [">=1.4.0", "<2.0.0"] accepts fixes and new features but not the next major version, which may change macros.
• dbt version requirements. Packages declare which dbt versions they support. An old package version can refuse to run on a new dbt; upgrading the package is usually the fix.
• Private packages. A Git URL with a token, read from a DBT_ENV_SECRET_ variable, installs a package from a private repository.

Tested with dbt Core 1.12 and dbt_utils 1.4.1.