dbt package dependency version conflicts

TL;DR

Pin exact versions in packages.yml, resolve the conflict by finding one version set all packages accept (usually by upgrading the laggard), and commit package-lock.yml so installs are reproducible. Version conflicts are a constraint problem; solve it with explicit pins, not hopeful ranges.

dbt package dependency version conflicts

Use this when

• dbt deps fails on version conflicts
• Two packages need different versions of a shared dependency
• You need reproducible package installs

Not for this skill when

• You are choosing model materializations
• You are choosing snapshot strategies
• You are writing unit tests

Steps

1. Read the actual conflict. dbt deps tells you who wants what:

Could not find a satisfactory version from options: [...]
Required by: package-a needs dbt-utils>=1.0,[1.2; package-b needs dbt-utils]=1.2

Expected output: the conflicting requirements named. The fix starts from this message, not from guessing.

1. Pin everything explicitly in packages.yml:

packages:
  - package: dbt-labs/dbt_utils
    version: 1.1.3
  - package: calogica/dbt_expectations
    version: 0.10.4

Expected output: deterministic resolution. Ranges (>=1.0,<2.0) feel flexible but let a fresh install resolve differently next month; exact pins do not.

1. Resolve the diamond by upgrading the laggard, not downgrading the leader:

If package-a needs dbt-utils[1.2 and package-b needs ]=1.2,
check whether package-a works with 1.2 anyway (often it does;
the bound was conservative). Upgrade package-a first.
Only pin the older version if the newer genuinely breaks it.

Expected output: a compatible set, usually on the newer versions. Maintainers set upper bounds conservatively; the real incompatibility is rarer than the declared one.

1. Commit the lock file so every environment installs identically:

dbt deps  # generates package-lock.yml
 git add package-lock.yml packages.yml

Expected output: CI, colleagues, and production install the exact same package versions. Without the lock file, two installs a month apart can differ.

1. When truly stuck, vendor the conflicting package:

Fork the package, relax or fix the bound, point packages.yml
at your git URL with a revision. Last resort, but it unblocks
you when upstream is slow and the bound is wrong.

Expected output: an unblocked pipeline with a documented fork. File the upstream issue too, so you can drop the fork later.

Variant phrasings

dbt deps version conflict

Read the requirements message (step 1), then pin and upgrade the laggard (steps 2-3).

dbt package-lock.yml

Generated by dbt deps; commit it for reproducible installs (step 4).

dbt packages.yml version pinning

Exact versions beat ranges for reproducibility. Ranges are for library authors; pins are for projects.

Why it happens

dbt packages declare version bounds on shared dependencies like dbt-utils. When two packages' bounds do not overlap, no version satisfies both and dbt deps fails. The bounds are often stricter than reality, so the fix is usually finding the overlap the authors were too cautious to declare.

Edge cases

• Git-based packages need a revision pin too; a branch name moves, a tag or SHA does not.
• Major version bumps of dbt-core itself (1.x to 2.x) invalidate many package bounds at once; upgrade packages as a batch.
• Private registry or Hub outages make dbt deps fail for network reasons; the error looks similar but the fix is retrying, not repinning.
• Removing a package from packages.yml does not remove it from package-lock.yml until you rerun dbt deps.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_y3-iE2h0zBRAZSD3yLDGLA