Version pinning and updates in dbt

Introduction

Version pinning helps keep your dbt project stable by using a fixed version. Updates let you get new features and fixes safely.

When you want to avoid unexpected errors from new dbt versions.

When your team needs everyone to use the same dbt version.

When you want to try new dbt features after testing them.

When you maintain multiple projects with different dbt versions.

When you want to plan updates carefully to avoid breaking changes.

Syntax

dbt

In your dbt project's packages.yml file:

packages:
  - package: dbt-labs/dbt_utils
    version: [">=0.7.0", "<0.8.0"]

The version field pins the package to a version range.

You can pin dbt core version in your environment or CI config, not in packages.yml.

Examples

This pins the dbt_utils package to exactly version 0.8.0.

dbt

packages:
  - package: dbt-labs/dbt_utils
    version: "0.8.0"

This allows any dbt_utils version from 0.7.0 up to but not including 0.9.0.

dbt

packages:
  - package: dbt-labs/dbt_utils
    version: ">=0.7.0,<0.9.0"

This fixes the dbt core version used in your environment.

dbt

# Pin dbt core version in your environment
pip install dbt-core==1.5.0

Sample Program

This example shows how you pin a package version in packages.yml and then check the installed version with dbt --version.

dbt

# Example: Pin dbt_utils package version and check installed version
# This is a conceptual example since dbt runs in CLI

# packages.yml content:
# packages:
#   - package: dbt-labs/dbt_utils
#     version: ">=0.8.0,<0.9.0"

# After running 'dbt deps', dbt_utils version in this range is installed.

# To check installed package version, run:
# dbt --version

# Output example:
# Installed version: 1.5.0
# Installed packages:
# - dbt_utils 0.8.4

print("Installed dbt_utils version: 0.8.4")

Important Notes

Always test your project after updating dbt or packages to catch issues early.

Use version ranges to allow minor updates but avoid big breaking changes.

Pinning dbt core version is done outside packages.yml, usually in your environment or CI setup.

Summary

Version pinning keeps your dbt project stable by fixing package or dbt core versions.

Use version ranges to balance stability and access to new features.

Always test after updates to avoid surprises.