atmos terraform init

Use this command to initialize the Terraform working directory for an Atmos component in a stack. This prepares the component for other Terraform operations.

atmos terraform init --help

Usage

Execute the terraform init command like this:

atmos terraform init <component> -s <stack> [options]

This command performs several initialization steps:

• Downloads and installs provider plugins
• Initializes the backend configuration
• Downloads modules referenced in the configuration
• Creates or updates the .terraform directory

Atmos Enhancements

Atmos enhances the init command with:

• Cleans .terraform/environment file before running
• Skips init automatically before other commands when nothing relevant has changed (see Automatic Initialization)
• Adds -reconfigure/-upgrade only when needed, or on every init if configured
• Supports passing varfile to init (OpenTofu feature) via --init-pass-vars flag
• Can be forced off entirely with --skip-init or init.mode: never

tip

Atmos automatically runs terraform init before executing plan and apply commands, but only when it's actually needed — running the same commands back-to-back doesn't pay for a redundant init. You typically don't need to run this manually unless you want to reinitialize with different options.

Examples

Basic Initialization

Initialize a component in a stack:

atmos terraform init vpc -s dev

Reconfigure Backend

Force reconfiguration of the backend:

atmos terraform init vpc -s dev -reconfigure

Upgrade Providers

Upgrade provider plugins to the latest allowed versions:

atmos terraform init vpc -s dev -upgrade

Backend Migration

Migrate from one backend to another:

atmos terraform init vpc -s dev -migrate-state

Skip Backend Initialization

Initialize without configuring the backend (useful for syntax validation):

atmos terraform init vpc -s dev -backend=false

Graph-backed Bulk Init

Run init for multiple components through the Terraform dependency graph:

# Initialize every Terraform component, in dependency order
atmos terraform init --all -s dev

# Initialize only selected components
atmos terraform init --components eks/apps,eks/cluster,vpc -s dev

Unlike destroy, init has no destructive-ordering requirement, so it keeps the natural forward dependency order: prerequisites are initialized before the components that depend on them.

Independent init nodes can run concurrently when --max-concurrency is greater than 1. Concurrent init disables the shared provider plugin cache for worker subprocesses, since it isn't safe for concurrent terraform init runs.

atmos terraform init --all -s dev --max-concurrency 4

Use --failure-mode keep-going to continue independent graph branches after one component fails. The default is fail-fast.

Automatic Initialization

Atmos runs terraform init automatically before plan, apply, destroy, shell, deploy (when deploy_run_init is enabled), and before resolving !terraform.output or atmos.Component — but only when init is actually needed.

By default (init.mode: auto), Atmos fingerprints the inputs that affect terraform init — the component's root .tf/.tf.json/.tofu/.tofu.json files, .terraform.lock.hcl, the Terraform CLI configuration, the resolved binary, relevant environment variables, and (when init.pass_vars is true) the varfile — and compares it against the fingerprint recorded after the last successful init. If nothing has changed, and the working directory still looks initialized (provider plugins present, modules downloaded, backend state present as applicable), Atmos skips init entirely. Running atmos terraform apply followed by atmos terraform output on the same component no longer pays for two full inits.

Atmos also decides -reconfigure and -upgrade per invocation instead of adding them unconditionally:

• init.reconfigure: auto (default) adds -reconfigure only when the backend configuration changed, on the first init, after a JIT working directory is re-provisioned, or for atmos terraform workspace.
• init.upgrade: auto (default) adds -upgrade automatically when Terraform/OpenTofu reports that one is required — for example, after a provider version constraint was raised beyond the locked version. Set init.upgrade: never to opt back out of automatic upgrades.

Set init.mode, init.reconfigure, or init.upgrade to always to force Atmos to add the corresponding behavior to every automatic init (the previous default), or to never to disable it entirely — for init.mode: never, unlike --skip-init, atmos terraform workspace select/new still forces a reconfigured init regardless, since it always needs one. Pinning a config edition from before September 12, 2026 restores the pre-this-feature always/never defaults for init.mode/ init.upgrade with no config changes. See Terraform Configuration for the full setting reference, environment variables, and flags.

If a skipped init turns out to have been necessary — for example a nested module changed, or part of .terraform was deleted by hand — Terraform/OpenTofu fails with a diagnostic such as "Backend initialization required" or "Required plugins are not installed" before touching any state. Atmos recognizes these diagnostics, runs the init that was skipped, and retries the command once. Atmos never runs -migrate-state as part of this recovery; a backend change requiring state migration always surfaces for you to handle explicitly.

You can force init off entirely for one invocation using the --skip-init flag, equivalent to --init-mode=never for that run:

atmos terraform plan vpc -s dev --skip-init

Backend Configuration

Atmos can automatically generate backend configuration files. When auto_generate_backend_file is enabled in your atmos.yaml:

components:
  terraform:
    auto_generate_backend_file: true

Atmos will:

1. Generate a backend.tf.json file with the appropriate backend configuration
2. Initialize Terraform with this backend configuration
3. Ensure state is stored in the correct location

Arguments

component (required)

Atmos component name to initialize.

Flags

--stack / -s (required)

Atmos stack name where the component is defined.

--dry-run (optional)

Show what would be executed without actually running the command.

atmos terraform init vpc -s dev --dry-run

--skip-init (optional)

This flag doesn't apply to the init command itself, but when used with other commands, it skips the automatic terraform init.

atmos terraform plan vpc -s dev --skip-init

--init-pass-vars (optional)

Pass the generated varfile to terraform init using the --var-file flag. This is useful with OpenTofu which supports passing a varfile to init to dynamically configure backends.

atmos terraform init vpc -s dev --init-pass-vars

--init-mode (optional)

Override init.mode for this invocation: auto (default, skip when nothing relevant changed), always (init before every command), or never (disables the ordinary implicit init, but unlike --skip-init does not suppress the forced reconfigure init that atmos terraform workspace select/new needs).

atmos terraform plan vpc -s dev --init-mode=always

--init-reconfigure (optional)

Override init.reconfigure for this invocation: auto (default, add -reconfigure only when the backend changed), always, or never. Supersedes --init-run-reconfigure when both are set.

atmos terraform plan vpc -s dev --init-reconfigure=always

--init-upgrade (optional)

Override init.upgrade for this invocation: auto (default, add -upgrade only when Terraform/OpenTofu reports it's required), always, or never.

atmos terraform plan vpc -s dev --init-upgrade=always

--ui (optional)

Enable streaming UI mode for real-time progress display during initialization. Shows provider downloads and plugin installation progress.

The UI automatically disables when output is piped, in CI environments, or when running unsupported commands.

--ui errors when combined with --max-concurrency greater than 1, since concurrently-scheduled components can't share one terminal for their full-screen UI sessions. Use --max-concurrency 1 (the default) with --ui, or drop --ui to run concurrently.

atmos terraform init vpc -s dev --ui

Use --ui=false to explicitly disable when enabled by config.

--all (optional)

Initialize all components in all stacks, in dependency order, through the Terraform dependency graph.

Environment variable: ATMOS_TERRAFORM_INIT_ALL

atmos terraform init --all -s dev

--affected (optional)

Initialize only the components affected by changes, in dependency order.

Environment variable: ATMOS_TERRAFORM_INIT_AFFECTED

atmos terraform init --affected

--max-concurrency (optional)

Maximum number of Terraform init components to execute concurrently when using --all, --affected, or --components. Defaults to 1 (sequential).

Environment variable: ATMOS_TERRAFORM_INIT_MAX_CONCURRENCY

atmos terraform init --all -s dev --max-concurrency 4

--failure-mode (optional)

Controls how the scheduler handles a failed component during multi-component init. Supported values:

• fail-fast (default) — stop scheduling new components after the first failure
• keep-going — continue independent graph branches, skipping only blocked dependents

Environment variable: ATMOS_TERRAFORM_INIT_FAILURE_MODE

atmos terraform init --all -s dev --failure-mode keep-going

--log-order (optional)

Controls how concurrent per-component logs are ordered when --max-concurrency is greater than 1.

Supported values:

• stream (default) — print log lines as they arrive, interleaved across components
• grouped — buffer each component's output and print it as a contiguous block after the component finishes

Environment variable: ATMOS_TERRAFORM_INIT_LOG_ORDER

atmos terraform init --all -s dev --max-concurrency 4 --log-order grouped

--include-dependencies (optional)

With a multi-component selection (--all, --components, --query, --stack, --tags, --labels, --affected), also initialize everything the selected components depend on (their prerequisites), in dependency order — even prerequisites in other stacks. Accepts an optional depth: the bare flag expands the full dependency chain, while --include-dependencies=1 bounds it to direct dependencies. Pass the depth with =; a space-separated value is not bound to the flag.

atmos terraform init --components=eks/apps -s dev --include-dependencies

Environment variable: ATMOS_INCLUDE_DEPENDENCIES

--include-dependents (optional)

With a multi-component selection, also initialize everything that depends on the selected components, in dependency order. Accepts an optional depth (for example, --include-dependents=2 for two levels).

atmos terraform init --components=vpc -s dev --include-dependents

Environment variable: ATMOS_INCLUDE_DEPENDENTS

Native Terraform Flags

The atmos terraform init command supports all native terraform init flags. To pass native Terraform flags, you have two options:

1. Direct flags - Pass Terraform flags directly if they don't conflict with Atmos flags
2. Double-dash separator - Use -- to explicitly separate Atmos flags from Terraform flags

Using the Double-Dash Separator

The -- separator is a common Unix convention that indicates "end of options". Everything after -- is passed directly to Terraform without interpretation by Atmos. This is useful when:

• You want to ensure a flag is passed to Terraform, not Atmos
• You're using flags that might conflict with Atmos flags
• You want to be explicit about which tool receives which flags

Example:

atmos terraform init vpc -s dev -- -backend-config="key=value" -upgrade

Native terraform init flags include:

-backend=false

Disable backend initialization.

atmos terraform init vpc -s dev -backend=false

-backend-config=PATH

Path to backend configuration file or key=value pairs.

atmos terraform init vpc -s dev -backend-config="key=value"

-force-copy

Suppress prompts about copying state data when initiating migration.

atmos terraform init vpc -s dev -force-copy

-from-module=SOURCE

Copy contents of module SOURCE into the current directory before initialization.

atmos terraform init vpc -s dev -from-module=git::https://example.com/module.git

-get=false

Disable downloading modules for this configuration.

atmos terraform init vpc -s dev -get=false

-input=false

Disable interactive prompts.

atmos terraform init vpc -s dev -input=false

-lock=false

Don't hold a state lock during backend migration.

atmos terraform init vpc -s dev -lock=false -force-copy

-lock-timeout=DURATION

Override the time Terraform will wait to acquire a state lock (default: 0s).

atmos terraform init vpc -s dev -lock-timeout=60s

-migrate-state

Reconfigure the backend and migrate any existing state.

atmos terraform init vpc -s dev -migrate-state

-no-color

Disable color codes in command output.

atmos terraform init vpc -s dev -no-color

-plugin-dir=PATH

Directory containing plugin binaries.

atmos terraform init vpc -s dev -plugin-dir=/usr/local/terraform/plugins

-reconfigure

Reconfigure the backend, ignoring any saved configuration.

atmos terraform init vpc -s dev -reconfigure

-upgrade

Upgrade modules and plugins as part of initialization.

atmos terraform init vpc -s dev -upgrade

Configuration

Configure default behavior for terraform init in your atmos.yaml:

components:
  terraform:
    init:
      # Skip init when nothing relevant changed (auto | always | never)
      mode: auto
      # Add -reconfigure only when the backend changed (auto | always | never)
      reconfigure: auto
      # Add -upgrade only when required (auto | always | never)
      upgrade: auto
      # Pass varfile to init (OpenTofu feature)
      pass_vars: true

    # Auto-generate backend configuration
    auto_generate_backend_file: true

These settings can also be controlled via environment variables:

export ATMOS_COMPONENTS_TERRAFORM_INIT_MODE=auto
export ATMOS_COMPONENTS_TERRAFORM_INIT_RECONFIGURE=auto
export ATMOS_COMPONENTS_TERRAFORM_INIT_UPGRADE=auto
export ATMOS_COMPONENTS_TERRAFORM_INIT_PASS_VARS=true
export ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_BACKEND_FILE=true

See Terraform Configuration for the deprecated init_run_reconfigure boolean and its mapping onto init.reconfigure.

Common Use Cases

Switching Between Backends

When migrating from local to remote state:

# First, update your backend configuration in the component
# Then migrate the state
atmos terraform init vpc -s dev -migrate-state

Upgrading Provider Versions

After updating provider version constraints:

# Upgrade to latest allowed versions
atmos terraform init vpc -s dev -upgrade

# Or clean and reinitialize
atmos terraform clean vpc -s dev
atmos terraform init vpc -s dev

CI/CD Initialization

For CI/CD pipelines, disable interactive prompts:

atmos terraform init vpc -s dev -input=false -no-color

Debugging Initialization Issues

Enable detailed logging:

export TF_LOG=DEBUG
atmos terraform init vpc -s dev

Related Commands

• atmos terraform plan - Generate execution plan
• atmos terraform apply - Apply changes
• atmos terraform clean - Clean terraform files
• atmos terraform workspace - Manage workspaces