# Configure Dependencies

The `dependencies` section has four sibling keys: `tools` (required CLI versions), `components` (other Atmos components this one depends on), `files` (file paths whose changes affect this component), and `folders` (folder paths whose changes affect this component). Tool dependencies pin CLI versions like Terraform, kubectl, or helm; `components` defines execution ordering between Atmos components, and `files`/`folders` declare watch-paths used by `atmos describe affected` and CI/CD integrations.

## Use Cases

- **Tool Version Requirements:** Ensure components use specific Terraform, kubectl, or helm versions
- **Team Consistency:** Version-control tool requirements for reproducible deployments
- **CI/CD Reliability:** Guarantee correct tool versions in automated pipelines
- **Execution Order:** Deploy dependent components in the correct sequence
- **Impact Analysis:** Let `atmos describe affected` find components impacted by changes to other components, files, or folders

## Tool Dependencies

The `dependencies.tools` section declares which CLI tool versions a component requires. Atmos automatically installs and uses the specified versions when executing the component.

### Configuration Scopes

Tool dependencies can be defined at multiple levels, with more specific levels taking precedence.

#### Project Defaults

The project's `.tool-versions` file supplies defaults for every command and component type: Terraform, Helmfile, Packer, Ansible, Helm, and Kubernetes component runs (including Terraform output and template lookups), workflows, custom commands, and hooks. The first version listed for each tool is its default. Every Atmos command inherits already-installed project selections on `PATH`; cached tools absent from the file and other cached versions are not added. Explicit `dependencies.tools` override this baseline. Downloads are controlled separately by the [`toolchain.install`](/cli/configuration/toolchain#install) policy, which defaults to `auto`:

- **`never`**
  Atmos installs nothing. Explicit 
  `dependencies.tools`
   and 
  `.tool-versions`
   tools join 
  `PATH`
   only when they are already installed. A missing 
  `dependencies.tools`
   entry is an error with a hint to run 
  `atmos toolchain install`
  . A missing 
  `.tool-versions`
   tool is skipped and the system 
  `PATH`
   is used.
- **`declared`**
  Atmos installs only explicit 
  `dependencies.tools`
  . Other runs inherit already-installed project selections without installing missing defaults. Workflows install every tool listed in 
  `.tool-versions`
   that is missing, because a workflow can call any project tool.
- **`auto` (default)**
  Component runs install their own executable from 
  `.tool-versions`
   when the file pins it, plus 
  `helm`
   for Helmfile components. The executable comes from the component's 
  `command`
  , then 
  `components.<type>.command`
   in 
  `atmos.yaml`
  , then the type default (
  `terraform`
  , 
  `helmfile`
  , 
  `packer`
  , 
  `ansible`
  ). A 
  `command`
   that is a path selects nothing, and native Kubernetes components run in process and select nothing. If the file does not pin the executable, Atmos installs nothing for it and uses the system 
  `PATH`
  . Every other tool in the file joins 
  `PATH`
   only if it is already installed (for example by 
  `atmos toolchain install`
  ). Custom commands and hooks install only their own 
  `dependencies.tools`
   and use already-installed 
  `.tool-versions`
   tools. Workflows install every tool listed in 
  `.tool-versions`
   that is missing, together with the workflow's own 
  `dependencies.tools`
  , before the first step runs.
- **`always`**
  Atmos installs every usable 
  `.tool-versions`
   tool for every run: components, custom commands, hooks, and workflows.

Projects pinned to an [edition](/cli/configuration/edition) dated before 2026-10-09 get `declared`, preserving their previous automatic download policy. Installed project selections remain the baseline under every policy.

An explicit `dependencies.tools` entry is installed when the policy permits it and always overrides the `.tool-versions` entry for the same tool without being constrained by it. Short names, configured aliases, and qualified names that resolve to the same tool are treated as one tool when Atmos compares the manifest with explicit dependencies: for example, `terraform: "1.8.5"` overrides `hashicorp/terraform 1.9.0` in `.tool-versions`. Atmos does not apply this matching between different explicit stack scopes, so use the same key at each scope.

Project defaults are best effort. Atmos skips `.tool-versions` entries whose version is `system`, `ref:...`, or `path:...`, whose version is a bare operator such as `~>` (write `~>1.9.0` without a space), or whose tool name Atmos cannot resolve (for example `nodejs`). Lines that list a tool without a version are skipped with a warning. Skipped entries never fail a run. When two entries name the same tool with the same version (for example `tofu 1.12.6` and `opentofu/opentofu 1.12.6`), Atmos uses one of them. When they name the same tool with different versions, Atmos stops with an error naming both entries.

The manifest is optional. If neither the manifest nor explicit dependencies declare a tool, Atmos uses the system `PATH`. Component overrides do not rewrite `.tool-versions`.

#### Global Level

Tool versions defined at the root level apply to all components:

**File:** `stacks/orgs/acme/_defaults.yaml`

```yaml
# Global tool dependencies
dependencies:
  tools:
    terraform: "1.9.8"      # All Terraform components use this version
    kubectl: "1.28.0"        # All kubectl commands use this version
```

#### Component-Type Level

Tool versions defined under `terraform`, `helmfile`, `packer`, or `ansible` apply to all components of that type:

**File:** `stacks/orgs/acme/plat/prod/_defaults.yaml`

```yaml
terraform:
  dependencies:
    tools:
      terraform: "1.9.8"     # All Terraform components use 1.9.8
      tflint: "0.44.1"       # All Terraform components use tflint 0.44.1

helmfile:
  dependencies:
    tools:
      helm: "3.13.0"         # All Helmfile releases use helm 3.13.0
      kubectl: "1.28.0"      # All Helmfile releases use kubectl 1.28.0

ansible:
  dependencies:
    tools:
      ansible: "2.16.0"      # All Ansible components use ansible 2.16.0
```

#### Component Level

Tool versions defined within a component override all higher-level settings:

**File:** `stacks/orgs/acme/plat/prod/us-east-1.yaml`

```yaml
components:
  terraform:
    vpc:
      dependencies:
        tools:
          terraform: "1.8.5"   # This component uses older Terraform version
          aws-cli: "2.13.0"    # Component-specific AWS CLI version
```

### Version Resolution

Tool dependencies support multiple version formats:

- **Exact version**

  Use a specific version: `"1.9.8"`
- **Latest version**

  Use the latest available version: `"latest"`
- **Semver constraint (planned)**

  Use semantic version ranges: `">=1.8.0"`, `"~>1.9.0"`

### Inheritance and Merge Behavior

Tool dependencies are merged from the most general to the most specific level:

1. **Project `.tool-versions`** (project defaults, applied as described in [Project Defaults](#project-defaults))
2. **Global `dependencies.tools`** (applies to all components)
3. **Component-type `terraform.dependencies.tools`** (applies to all components of that type)
4. **Component `components.terraform.<name>.dependencies.tools`** (applies to specific component)

Explicit dependencies always override `.tool-versions` defaults. Within the explicit stack scopes, more specific levels override less specific levels subject to existing parent version constraints. For example:

**File:** `Example: Version Override`

```
# Global default
dependencies:
  tools:
    terraform: "1.9.8"

# Component-type override
terraform:
  dependencies:
    tools:
      terraform: "1.9.8"
      tflint: "0.44.1"     # Added for all Terraform components

# Component-specific override
components:
  terraform:
    legacy-vpc:
      dependencies:
        tools:
          terraform: "1.5.0"  # This component uses older version
          tflint: "0.44.1"    # Inherited from component-type level
```

Result:

- Most Terraform components use Terraform 1.9.8
- `legacy-vpc` component uses Terraform 1.5.0
- All Terraform components use tflint 0.44.1

### Integration with Toolchain

Tool dependencies integrate seamlessly with the [toolchain management system](/cli/commands/toolchain/usage):

1. **Automatic Installation:** When you run a component, Atmos installs the required tool versions automatically
2. **Version Isolation:** Each component uses its declared versions, isolated from other components
3. **Cache Efficiency:** Tools are cached and reused across components with the same version requirements

Example workflow:

```bash
# Component declares terraform: "1.9.8"
atmos terraform plan vpc -s prod

# Atmos automatically:
# 1. Checks if terraform 1.9.8 is installed
# 2. Installs it if missing (from toolchain registries)
# 3. Executes: terraform plan (using 1.9.8)
```

### Complete Tool Dependencies Example

**File:** `stacks/orgs/acme/plat/prod/us-east-1.yaml`

```yaml
# Global tool dependencies (all components)
dependencies:
  tools:
    terraform: "1.9.8"
    kubectl: "1.28.0"

# Component-type dependencies (all Terraform components)
terraform:
  dependencies:
    tools:
      terraform: "1.9.8"      # Override global if needed
      tflint: "0.44.1"        # Terraform-specific tool
      tfsec: "1.28.0"         # Security scanning
      aws-cli: "latest"       # Use latest AWS CLI

# Component-type dependencies (all Helmfile releases)
helmfile:
  dependencies:
    tools:
      helm: "3.13.0"
      kubectl: "1.28.0"
      helmfile: "0.157.0"

# Component-specific dependencies
components:
  terraform:
    vpc:
      dependencies:
        tools:
          terraform: "1.9.8"    # Use default
          aws-cli: "2.13.0"     # Component needs specific AWS CLI version

    legacy-app:
      dependencies:
        tools:
          terraform: "1.5.0"    # Legacy component requires older version
          aws-cli: "2.10.0"

  helmfile:
    monitoring:
      dependencies:
        tools:
          helm: "3.13.0"
          kubectl: "1.28.0"
```

## Component Dependencies

The `dependencies.components` section declares ordering relationships between Atmos components. Use it to express that one component must be applied before another. These dependencies are used by `atmos describe dependents` to find downstream consumers, by `atmos describe affected` to propagate impact through the dependency graph, and by CI/CD integrations to apply components in the correct order.

For the full reference — cross-stack dependencies, cross-type (`kind`) dependencies, merge behavior, and migration from `settings.depends_on` — see the dedicated [Component Dependencies](/stacks/dependencies/components) page.

### Quick Example

**File:** `stacks/catalog/vpc.yaml`

```yaml
components:
  terraform:
    vpc:
      vars:
        name: vpc

    subnet:
      dependencies:
        components:
          - name: vpc          # subnet depends on vpc
      vars:
        vpc_id: !terraform.output vpc.vpc_id
```

## File and Folder Dependencies

The `dependencies.files` and `dependencies.folders` sibling keys declare path-based dependencies. When `atmos describe affected` detects a change to one of these paths, the declaring component is marked as affected — even when no component code or stack configuration changed.

Use this to wire components to external assets like Lambda source code, configuration files, or schema definitions that live outside the component directory.

**File:** `stacks/catalog/lambda.yaml`

```yaml
components:
  terraform:
    lambda-function:
      dependencies:
        files:
          - configs/lambda-settings.json
        folders:
          - src/lambda/my-function
```

:::info Legacy inline shape
The `kind: file` / `kind: folder` entries inside `dependencies.components[]` (shipped in v1.210.0) still parse and behave identically. New configurations should prefer the `dependencies.files` and `dependencies.folders` sibling keys for clarity.
:::

## Best Practices

1. **Pin Versions Explicitly** - Use exact versions (`"1.9.8"`) instead of `"latest"` for production
2. **Consistent Team Standards** - Define global defaults in `_defaults.yaml` files
3. **Component-Specific Overrides** - Only override when necessary (legacy code, compatibility)
4. **Document Reasons** - Add comments explaining why a component uses a different version
5. **Test Before Upgrading** - Test tool version changes in dev/staging before production

## Related Documentation

- [Component Dependencies](/stacks/dependencies/components) - Detailed component dependency configuration
- [Toolchain Management](/cli/commands/toolchain/usage) - Installing and managing CLI tools
- [Toolchain Configuration](/cli/configuration/toolchain/) - Configuring toolchain behavior
- [Legacy `settings.depends_on`](/stacks/settings/depends_on) - Deprecated dependency format (kept for reference)
- [YAML Functions](/functions/yaml) - Using `!terraform.output` and other functions for cross-component dependencies
- [`atmos describe affected`](/cli/commands/describe/affected) - Detect components affected by changes