Pulling in and using a dbt package

dbt packages let you reuse macros, models, and tests published by dbt Labs or the community, saving you from rewriting common logic like date spines, schema tests, or source-specific transformations. Packages are declared in packages.yml, installed with 'dbt deps' into the dbt_packages directory, and version-pinned to ensure reproducible builds. dbt Hub is the standard registry for discovering published packages, though private/git-hosted packages are also supported.

1 · Learn the must-know

• 1Packages are declared in packages.yml (not dependencies.yml, which is used only for cross-project 'dbt Mesh' style referencing) and fetched into the dbt_packages folder via 'dbt deps'.
• 2You should pin package versions (or version ranges) in packages.yml to avoid unexpected breaking changes when running 'dbt deps' in CI/CD or production.
• 3dbt-utils is the most widely used community package, providing macros like date_spine, surrogate_key generation, and cross-database compatible functions (e.g., dbt_utils.generate_surrogate_key).
• 4Macros and models from installed packages are referenced with the package name prefix, e.g., {{ dbt_utils.star(...) }} or ref('package_name', 'model_name'), and package models are materialized in your project's target schema unless configured otherwise.
• 5The dbt_packages directory is typically gitignored, so 'dbt deps' must be rerun after cloning a repo or in every CI run to restore installed packages.
• 6Package version conflicts can occur when two installed packages depend on incompatible versions of a shared dependency (like dbt-utils), requiring careful version alignment in packages.yml.

2 · Check your understanding