# Imports

Atmos supports importing other CLI configurations to break large configurations into smaller, manageable pieces. Use imports to organize configuration by section or to share common settings across projects.

## Configuration

Imports are defined in the `import` section of `atmos.yaml`:

**File:** `atmos.yaml`

```yaml
import:
  # Load the Atmos configuration from the main branch of the 'cloudposse/atmos' repository
  - "https://raw.githubusercontent.com/cloudposse/atmos/refs/heads/main/atmos.yaml"
  # Then merge the configs
  - "configs.d/**/*"
  # Finally, override some logging settings
  - "./logs.yaml"
```

## Import Types

Imports can be any of the following:

- **Remote URL**

  Load configuration from a remote URL. Always use HTTPS URLs and verify the authenticity of remote sources.
  ```yaml
  import:
    - "https://raw.githubusercontent.com/cloudposse/atmos/refs/heads/main/atmos.yaml"
  ```
- **Specific Path**

  Load a specific configuration file by path. Relative paths are resolved from the `atmos.yaml` directory.
  ```yaml
  import:
    - "./logs.yaml"
    - "configs/terraform.yaml"
  ```
- **Glob Patterns**

  Use wildcard globs (`*`), including recursive globs (`**`), to import multiple files. Only files ending in `.yml` or `.yaml` will be considered.
  ```yaml
  import:
    - "configs.d/**/*"
    - "*.yaml"
  ```

:::tip Pro-Tip
Atmos supports [POSIX-style greedy Globs](https://en.wikipedia.org/wiki/Glob_\(programming\)) for all file names/paths (double-star/globstar `**` is supported as well)
:::

## Merge Order

Imported configurations are deep-merged in order. The last file in the list supersedes settings in preceding imports:

1. First imported file (lowest priority)
2. Second imported file
3. … (middle files)
4. Last imported file (highest priority)
5. Settings in the main `atmos.yaml` (highest priority)

## Example: Organizing by Section

Break a large configuration into section-specific files:

```
configs.d/
├── base.yaml       # Base paths and general settings
├── terraform.yaml  # Terraform component settings
├── helmfile.yaml   # Helmfile component settings
├── stacks.yaml     # Stack configuration
├── workflows.yaml  # Workflow settings
└── logs.yaml       # Logging configuration
```

**File:** `atmos.yaml`

```yaml
import:
  - "configs.d/**/*"

# Override specific settings if needed
logs:
  level: Debug
```

## Remote Imports

:::warning Be Careful with Remote Imports

- Always use HTTPS URLs (not HTTP)
- Verify the authenticity of remote sources
- Consider pinning to specific commit hashes instead of branch references for stability
  :::

**Example with pinned commit:**

```yaml
import:
  # Pinned to specific commit for reproducibility
  - "https://raw.githubusercontent.com/cloudposse/atmos/abc123def456/atmos.yaml"
```

### Caching Remote Imports

Two default behaviors apply, depending on the import form. A `git::` import that uses a subdirectory
(e.g. `git::https://github.com/org/repo.git//path?ref=main`) re-clones the source repo on every `atmos`
invocation, so mutable refs (e.g. `?ref=main`) always stay current. A plain remote URL (no `git::`
subdirectory) is cached indefinitely instead — once downloaded, that content is reused until the cache is
cleared.

Set `imports.ttl` to change either default. When set, it applies to every remote import the same way: a
`git::` subdirectory import is cached and reused across invocations instead of always re-cloning, and a
plain URL import expires after `ttl` instead of being cached forever. Use the same setting stack manifest
imports already support (see [remote stack imports](/stacks/imports#caching-remote-imports)):

```yaml title="atmos.yaml"
imports:
  ttl: 5m
```

This is a single global default; root `import:` entries are plain strings and don't support a per-import
`ttl` override the way stack manifest imports do. `ttl` accepts durations like `0s` (always re-fetch),
`5m`, `1h`, `7d`, or keywords like `daily`. Pin to an immutable `?ref=<tag>` (or commit SHA) with a longer
`ttl` for maximum reuse; keep `ttl` short for mutable refs like `main` so the config stays fresh. Leave
`ttl` unset to keep each import form's own default behavior described above.

## Limitations

- Templated imports of Atmos configuration are not supported (unlike stacks)
- Only `.yml` and `.yaml` files are processed when using glob patterns

## See Also

- [CLI Configuration](/cli/configuration) — Overview of CLI configuration
- [YAML Functions](/cli/configuration#yaml-functions) — Dynamic values in configuration