"dbt deps" is the dbt CLI command that installs, updates, and manages external package dependencies declared in a dbt project’s packages.yml file.
If you build data pipelines with dbt, you’ve probably seen references to dbt deps
. This command may look innocuous, but it is the beating heart of dbt’s package-management system. Mastering it will save you hours of reinventing the wheel, keep your projects DRY, and help teams standardize analytics engineering practices across repositories.
dbt deps
?The dbt deps
command reads the packages.yml
file in your dbt project, resolves the listed package versions, downloads each package from its source (usually GitHub), and places them in the dbt_packages/
directory. In short, it is dbt’s dependency-management workflow—akin to pip install -r requirements.txt
for Python or npm install
for JavaScript.
dbt deps
Works Under the Hoodpackages.yml
dbt scans the YAML file for a packages
key. Each listed package must include at least one of the following selectors:
git
– URL of a Git repositoryregistry
– Identifier on the dbt Hub (e.g., dbt-labs/dbt_utils
)You can additionally specify version
, revision
, or branch
constraints.
dbt employs Semantic Versioning rules to find the highest compatible tag that satisfies the constraint. For Git sources, you can pin to a commit SHA for immutability.
dbt downloads each package as a zip archive, extracts it into dbt_packages/
, and records a manifest in packages.lock
so that subsequent installs are repeatable.
On the next dbt run
, the models, macros, and tests from dependencies are merged into your project’s compilation graph. Namespacing keeps them isolated—e.g., you would call a macro via {{ dbt_utils.date_spine(...) }}
.
# packages.yml
packages:
- package: dbt-labs/dbt_utils
version: ">=0.9.0,<1.0.0"
- git: "https://github.com/calogica/dbt_expectations.git"
revision: "0.8.4"
Running dbt deps
will:
dbt_utils
0.9.xdbt_expectations
at tag 0.8.4
packages.lock
file so your CI pipeline can later execute dbt deps --no-version-check
for speedAlways specify an upper bound (<1.0.0
) or a fixed tag/SHA to avoid unplanned breaking changes.
packages.lock
Treat it like package-lock.json
; it guarantees deterministic environments across machines and CI jobs.
Schedule quarterly or sprintly dependency upgrades. Use dbt deps --warn-error
in CI to block deprecated packages.
Prefer {{ dbt_utils.
> macros over copying them into your own repo. That keeps upgrade paths smooth.
Running dbt deps
without constraining versions can silently introduce breaking changes. Solution: set semantic version ranges or pin SHAs.
dbt_packages/
These vendor directories change per OS and are regenerated by the command. Keep them out of Git by adding dbt_packages/
to .gitignore
.
If teammates run dbt deps
with different version ranges, their lock files may diverge. Enforce CI checks that fail on uncommitted packages.lock
changes.
Galaxy is a modern, memory-light SQL editor. Because dbt deps
is executed from the shell or in CI pipelines, the typical workflow is:
dbt deps
in your terminal or CI job.Galaxy does not run dbt deps
directly, but its editor can read the compiled objects created by the command, making model exploration faster with autocomplete and metadata discovery.
Think of dbt deps
as your analytics engineering package manager. It keeps your toolchain lean, shareable, and version-safe. Follow the best practices above, and you’ll spend less time chasing dependency bugs and more time delivering insights.
Dependency management is critical for maintainable analytics engineering. Without a reliable, version-controlled workflow, teams end up copy-pasting macros, suffering from hidden bugs, and spending countless hours upgrading code. dbt deps solves this by providing a deterministic installation mechanism analogous to pip or npm. Mastering it enables reproducible builds, easy sharing of best-practice packages like dbt_utils, and smoother CI/CD pipelines.
No. dbt deps
only installs packages; it does not compile or execute models. You still need to run dbt run
or dbt build
afterward.
Run it whenever you change packages.yml
or pull changes that might affect dependencies. Many teams run it at the start of every CI job for determinism.
While Galaxy is a SQL editor and does not execute CLI commands directly, you can run dbt deps
in your terminal or CI pipeline and then use Galaxy’s AI-powered autocomplete to explore the models and macros it installs.
dbt applies a namespace based on the package name, so you would call the macro via {{ package_name.macro_name() }}
to prevent collisions.