# Version Pinning

Pin your project to a specific Atmos version using `version.use` in `atmos.yaml`. When configured, Atmos automatically downloads the specified version (if not already installed) and re-executes itself, ensuring everyone on your team uses the same version.

## Configuration

**File:** `atmos.yaml`

```yaml
version:
  use: "1.199.0"
```

When any `atmos` command runs, it will:

1. Check if the requested version is already installed
2. Download and install it automatically if needed
3. Re-execute the command with the correct version

Versions are cached in `~/.atmos/bin/cloudposse/atmos/{version}/`.

## Supported Version Formats

- **Exact semver**

  A specific release version (e.g., `1.199.0`). This is the recommended format for production use.
  ```yaml
  version:
    use: "1.199.0"
  ```
- **`latest`**

  Resolves to the latest available release from GitHub.
  ```yaml
  version:
    use: "latest"
  ```
- **`pr:<number>`**

  Install from a pull request's build artifacts. Useful for testing changes before they are released.
  ```yaml
  version:
    use: "pr:1234"
  ```
- **`sha:<hash>`**

  Install from a specific commit's build artifacts.
  ```yaml
  version:
    use: "sha:ceb7526"
  ```
- **`ref:<name>`**

  Install from the latest commit of a **branch or tag**, using that commit's CI build artifacts.
  The ref is resolved to its current commit on every run, so a mutable branch like `main` always
  tracks the latest build; the resolved commit is cached, so unchanged refs do not reinstall.
  ```yaml
  version:
    use: "ref:main"        # latest main build
  ```
  Accepts branch names, tag names, and slash-qualified refs:
  ```bash
  atmos --use-version=ref:main             # branch
  atmos --use-version=ref:release/v1.199    # branch with a slash
  atmos --use-version=ref:v1.199.0          # tag (the tag's commit artifact, not the release)
  atmos --use-version=ref:heads/main        # explicit branch (disambiguation)
  atmos --use-version=ref:tags/v1.199.0     # explicit tag (disambiguation)
  ```
  Like `pr:` and `sha:`, this installs **CI build artifacts** (retained for 90 days), not released
  binaries. For an older tag whose artifacts have expired, use the plain semver form (e.g.
  `1.199.0`) to install the release instead.

## Command-Line Override

Override the configured version for a single command using the `--use-version` flag:

```bash
atmos --use-version 1.201.0 terraform plan -s mystack
```

## Precedence

Version sources are evaluated in this order (highest to lowest priority):

| Priority | Source | Example |
|----------|--------|---------|
| 1 | `--use-version` flag | `atmos --use-version 1.201.0 terraform plan` |
| 2 | `ATMOS_VERSION_USE` env var | `ATMOS_VERSION_USE=1.201.0 atmos terraform plan` |
| 3 | `ATMOS_VERSION` env var | `ATMOS_VERSION=1.201.0 atmos terraform plan` |
| 4 | `version.use` in `atmos.yaml` | `version: use: "1.199.0"` |

The `--use-version` flag and `ATMOS_USE_VERSION` env var both set `ATMOS_VERSION_USE` internally,
so they share the same priority level.

## Environment Variables

- **`ATMOS_USE_VERSION`**

  Specify which version of Atmos to use. This is the env var equivalent of the `--use-version` flag.
  Internally, it feeds the flag value which sets `ATMOS_VERSION_USE`.
  ```bash
  ATMOS_USE_VERSION=1.199.0 atmos terraform plan -s mystack
  ```
- **`ATMOS_VERSION_USE`**

  The internal env var checked directly by the version resolution logic. Set automatically by the
  `--use-version` flag and `ATMOS_USE_VERSION`. Can also be set directly for highest precedence.
  ```bash
  ATMOS_VERSION_USE=1.199.0 atmos terraform plan -s mystack
  ```
- **`ATMOS_VERSION`**

  Convenience alias matching conventions used by tools like `tfenv` and `goenv`.
  Lower precedence than `ATMOS_VERSION_USE`.
  ```bash
  export ATMOS_VERSION=1.199.0
  ```

## Examples

### Pin Project to a Specific Version

**File:** `atmos.yaml`

```yaml
version:
  use: "1.199.0"
```

### Environment-Specific Versions with Profiles

Use [profiles](/cli/configuration/profiles) to specify different versions per environment:

```yaml title="profiles/dev/atmos.yaml"
version:
  use: "1.201.0"  # Latest version for development
```

```yaml title="profiles/prod/atmos.yaml"
version:
  use: "1.199.0"  # Stable version for production
```

Activate a profile:

```bash
atmos --profile dev terraform plan -s mystack

# Or via environment variable
ATMOS_PROFILE=prod atmos terraform apply -s mystack
```

### CI/CD Pipelines

Pin the version in your CI environment:

```yaml title=".github/workflows/deploy.yml"
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      ATMOS_VERSION: "1.199.0"
    steps:
      - uses: actions/checkout@v6
      - name: Deploy
        run: atmos terraform apply -s production/mystack --auto-approve
```

### Combined with Version Constraints

Use `version.use` to pin the version and `version.constraint` to enforce a minimum across the team:

**File:** `atmos.yaml`

```yaml
version:
  use: "1.199.0"
  constraint:
    require: ">=1.100.0"
    enforcement: fatal
```

## See Also

- [Version Configuration](/cli/configuration/version) — Overview of all version settings
- [Version Check](/cli/configuration/version/check) — Automatic update checking
- [Version Constraints](/cli/configuration/version/constraint) — Enforce version requirements
- [Atmos Version Management](/howto/atmos-version-management) — How-to guide with profiles
- [Toolchain Commands](/cli/commands/toolchain/usage) — Manage installed tool versions