# 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.

_\[Video: atmos terraform init]_

## Usage

Execute the `terraform init` command like this:

```shell
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

:::info 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](#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:

```shell
atmos terraform init vpc -s dev
```

### Reconfigure Backend

Force reconfiguration of the backend:

```shell
atmos terraform init vpc -s dev -reconfigure
```

### Upgrade Providers

Upgrade provider plugins to the latest allowed versions:

```shell
atmos terraform init vpc -s dev -upgrade
```

### Backend Migration

Migrate from one backend to another:

```shell
atmos terraform init vpc -s dev -migrate-state
```

### Skip Backend Initialization

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

```shell
atmos terraform init vpc -s dev -backend=false
```

### Graph-backed Bulk Init

Run init for multiple components through the Terraform dependency graph:

```shell
# 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.

```shell
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`](/functions/yaml/terraform.output) or
[`atmos.Component`](/functions/template/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](/cli/configuration/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](/cli/configuration/components/terraform#configuration-reference) 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:

```shell
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`:

```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.
  ```shell
  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`.
  ```shell
  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.
  ```shell
  atmos terraform init vpc -s dev --init-pass-vars
  ```
- **`--init-mode` (optional)**

  Override [`init.mode`](/cli/configuration/components/terraform#configuration-reference) 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).
  ```shell
  atmos terraform plan vpc -s dev --init-mode=always
  ```
- **`--init-reconfigure` (optional)**

  Override [`init.reconfigure`](/cli/configuration/components/terraform#configuration-reference) for this invocation: `auto` (default, add `-reconfigure` only when the backend changed), `always`, or `never`. Supersedes `--init-run-reconfigure` when both are set.
  ```shell
  atmos terraform plan vpc -s dev --init-reconfigure=always
  ```
- **`--init-upgrade` (optional)**

  Override [`init.upgrade`](/cli/configuration/components/terraform#configuration-reference) for this invocation: `auto` (default, add `-upgrade` only when Terraform/OpenTofu reports it's required), `always`, or `never`.
  ```shell
  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.
  ```shell
  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`
  ```shell
  atmos terraform init --all -s dev
  ```
- **`--affected` (optional)**

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

  **Environment variable:** `ATMOS_TERRAFORM_INIT_AFFECTED`
  ```shell
  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`
  ```shell
  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`
  ```shell
  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`
  ```shell
  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.
  ```shell
  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).
  ```shell
  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

:::tip 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:**

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

:::

Native `terraform init` flags include:

- **`-backend=false`**

  Disable backend initialization.
  ```shell
  atmos terraform init vpc -s dev -backend=false
  ```
- **`-backend-config=PATH`**

  Path to backend configuration file or key=value pairs.
  ```shell
  atmos terraform init vpc -s dev -backend-config="key=value"
  ```
- **`-force-copy`**

  Suppress prompts about copying state data when initiating migration.
  ```shell
  atmos terraform init vpc -s dev -force-copy
  ```
- **`-from-module=SOURCE`**

  Copy contents of module SOURCE into the current directory before initialization.
  ```shell
  atmos terraform init vpc -s dev -from-module=git::https://example.com/module.git
  ```
- **`-get=false`**

  Disable downloading modules for this configuration.
  ```shell
  atmos terraform init vpc -s dev -get=false
  ```
- **`-input=false`**

  Disable interactive prompts.
  ```shell
  atmos terraform init vpc -s dev -input=false
  ```
- **`-lock=false`**

  Don't hold a state lock during backend migration.
  ```shell
  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).
  ```shell
  atmos terraform init vpc -s dev -lock-timeout=60s
  ```
- **`-migrate-state`**

  Reconfigure the backend and migrate any existing state.
  ```shell
  atmos terraform init vpc -s dev -migrate-state
  ```
- **`-no-color`**

  Disable color codes in command output.
  ```shell
  atmos terraform init vpc -s dev -no-color
  ```
- **`-plugin-dir=PATH`**

  Directory containing plugin binaries.
  ```shell
  atmos terraform init vpc -s dev -plugin-dir=/usr/local/terraform/plugins
  ```
- **`-reconfigure`**

  Reconfigure the backend, ignoring any saved configuration.
  ```shell
  atmos terraform init vpc -s dev -reconfigure
  ```
- **`-upgrade`**

  Upgrade modules and plugins as part of initialization.
  ```shell
  atmos terraform init vpc -s dev -upgrade
  ```

## Configuration

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

```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:

```shell
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](/cli/configuration/components/terraform#configuration-reference) 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:

```shell
# 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:

```shell
# 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:

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

### Debugging Initialization Issues

Enable detailed logging:

```shell
export TF_LOG=DEBUG
atmos terraform init vpc -s dev
```

## Related Commands

- [`atmos terraform plan`](/cli/commands/terraform/plan) - Generate execution plan
- [`atmos terraform apply`](/cli/commands/terraform/apply) - Apply changes
- [`atmos terraform clean`](/cli/commands/terraform/clean) - Clean terraform files
- [`atmos terraform workspace`](/cli/commands/terraform/workspace) - Manage workspaces