# Install Atmos

There are many ways to install Atmos. Choose the method that works best for you!

To check what version of Atmos you have installed, just run `atmos version`. The latest version of Atmos is _(see latest release)_.

To find the latest available version of Atmos, visit the [Releases Page](https://github.com/cloudposse/atmos/releases). The latest version will always be available for download here.

## Using OS Package Managers

Atmos has native packages for macOS and every major Linux distribution. We also supply binary releases for Windows.

### macOS

#### macOS (OSX)

From Homebrew, install directly by running:

```shell
brew install atmos
```

#### Pro tip! Use a `Brewfile`

Create a `Brewfile` in your [Atmos project](/projects), and add `brew "atmos"`. This way, you can ensure that everyone on your team is using the same version of Atmos.

**File:** `Brewfile`

```
brew "atmos", "(see latest release)"
```

Then just run `brew install` in the same directory as the `Brewfile`.

### Debian/Ubuntu

#### Debian Linux (DEB)

On Debian, use the Cloud Posse package repository provided by Cloudsmith:

```shell
# Add the Cloud Posse package repository hosted by Cloudsmith
apt-get update && apt-get install -y apt-utils curl
curl -1sLf 'https://dl.cloudsmith.io/public/cloudposse/packages/cfg/setup/bash.deb.sh' │ bash

# Install atmos
apt-get install atmos@="${ATMOS_VERSION}-*"
```

### RedHat/CentOS

#### RedHat/CentOS Linux (RPM)

On RedHat or CentOS, use the Cloud Posse package repository provided by Cloudsmith:

```shell
curl -1sLf 'https://dl.cloudsmith.io/public/cloudposse/packages/setup.rpm.sh' │ sudo -E bash

# Install atmos
sudo yum install atmos-${ATMOS_VERSION}.x86_64
```

### Alpine Linux

#### Alpine Linux (APK)

On Alpine, use the Cloud Posse package repository provided by Cloudsmith:

```shell
# Install the Cloud Posse package repository hosted by Cloudsmith
curl -fsSL 'https://dl.cloudsmith.io/public/cloudposse/packages/setup.alpine.sh' │ bash

# Install atmos
apk add atmos@cloudposse
```

### NixOS

#### NixOS

On NixOS, run the following command to install:

```shell
nix-env -iA nixpkgs.atmos
```

To get the latest version, you may need to update the Nix config to add "unstable" packages.

For example, in `~/.config/nixpkgs/config.nix` add the following line to the file:

```console
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
```

Then run the following to install:

```shell
nix-shell -p atmos
```

### Windows

#### Windows via scoop.sh

On Windows, run the following command to install:

```shell
scoop install atmos
```

**NOTE:** Don't have `scoop`? Install it first from https://scoop.sh/

## Other Ways to Install

Atmos has a few other ways to install, including using Go, asdf, mise, aqua, building from source, or using the automatic installer.

### Native Version Manager

#### Install with Atmos Version Manager

Atmos includes a built-in version manager that can install and manage multiple versions of Atmos. This is particularly useful for:

- Teams that need to pin specific versions per project
- Switching between different versions for different projects
- Auto-updating when a new version is available

Install a specific version:

atmos version install _(see latest release)_

List available versions on GitHub:

```shell
atmos version list
```

List locally installed versions:

```shell
atmos version list --installed
```

Uninstall a specific version:

atmos version uninstall _(see latest release)_

#### Pin Version Per Project

You can pin a specific version of Atmos for your project by adding the following to your `atmos.yaml`:

**File:** `atmos.yaml`

```yaml
version:
use: (see latest release)
```

When `version.use` is configured, Atmos will automatically use the specified version, installing it if needed.

#### Command-Line Flag

Use the `--use-version` global flag to run a specific version for a single command:

```shell
# Run terraform plan with Atmos 1.160.0
atmos --use-version=1.160.0 terraform plan myapp -s dev
```

#### Environment Variables

You can also specify the version using environment variables:

```shell
# Set the Atmos version to use (matches version.use config path)
export ATMOS_VERSION_USE=1.160.0

# Or use the convenience alias
export ATMOS_VERSION=1.160.0
```

**Precedence order:** `--use-version` flag / `ATMOS_VERSION_USE` > `ATMOS_VERSION` > `version.use` in config file

**NOTE:** You need an initial installation of Atmos to bootstrap the version manager. Use any installation method above to get started.

### Go

#### Install with Go

Install the latest version:

```shell
go install github.com/cloudposse/atmos
```

Grab a specific version:

go install github.com/cloudposse/atmos@_(see latest release)_

Or specifically request the latest version.

```shell
go install github.com/cloudposse/atmos@latest
```

**NOTE:** Since the version is passed in via `-ldflags` during the build, when running `go install` without using `-ldflags`, the CLI will return `0.0.1` when running `atmos version`.

### asdf

#### Install with asdf

Install plugin dependencies as listed in [asdf-atmos repository](https://github.com/cloudposse/asdf-atmos#dependencies):

```shell
apt-get update && apt-get install -y bash curl tar
```

Install the plugin:

```shell
asdf plugin add atmos https://github.com/cloudposse/asdf-atmos.git
```

Install a specified version:

asdf install atmos _(see latest release)_

Alternatively, create a `.tool-versions` file in your project to specify a consistent version for the users:

**File:** `.tool-versions`

```
atmos (see latest release)
```

Then, run `asdf install` in the same directory.

**NOTE:** Don't have `asdf`? Install it first from [here](https://asdf-vm.com/guide/getting-started.html)

### Mise

#### Install with Mise

Install a specified version:
mise use atmos@_(see latest release)_

Alternatively, create a `.mise.toml` file in your repository to specify a consistent version for the users:

**File:** `.mise.toml`

```toml
[tools]
atmos = '(see latest release)'
```

Then, run `mise install` in the same directory.

**NOTE:** Don't have `mise`? Install it first from [here](https://mise.jdx.dev/getting-started.html)

### aqua

#### Install with aqua

[aqua](https://aquaproj.github.io/) is a CLI Version Manager.
aqua allows you to manage multiple versions of CLI tools, making it easy to switch between different versions of Atmos and other tools in your projects.

Create `aqua.yaml` by `aqua init`:

```shell
aqua init
```

Add atmos to aqua.yaml:

```shell
aqua g -i cloudposse/atmos
```

Then, run `aqua install` in the same directory.

**NOTE:** Don't have `aqua`? Install it first from [here](https://aquaproj.github.io/docs/install)

### From Source

#### Build from Source

```shell
make build
```

or run this and replace `$version` with the version that should be returned with `atmos version`.

```shell
go build -o build/atmos -v -ldflags "-X 'github.com/cloudposse/atmos/pkg/version.Version=$version'"
```

### Automatic Installer

#### Automatic Installer

If you're not sure which method to use, you can always use the automatic installer. It will figure out which
of the mechanisms above to use, and perform it.

Paste the following into a macOS Terminal or Linux shell prompt.

```shell
curl -fsSL https://atmos.tools/install.sh | bash
```

:::note
The latest version of Atmos (_(see latest release)_) might not be available with third-party package managers.
:::

## Download Binaries from Releases Page

- Go to [Releases Page](https://github.com/cloudposse/atmos/releases)

- Download the binary for your operating system and architecture. Replace `${version}` with the desired version

  - e.g. If you’re on a Mac (M1/M2/M3), download the `atmos_${version}_darwin_arm64` binary
  - e.g. If you’re on an Intel Mac, download the `atmos_${version}_darwin_amd64` binary
  - e.g. If you’re on Windows, download `atmos_${version}_windows_amd64.exe`, etc.

- Rename the downloaded file to `atmos` (optional)

- Add the execution bit to the binary (e.g. on Linux and Mac, run `chmod u+x atmos`)

- Place the binary somewhere on your `PATH` (e.g. on Linux and Mac: `mv atmos /usr/local/bin/`)

## Set Up Your Terminal

Atmos is a modern CLI with a Text-based UI (TUI), as such, for the best experience we recommend ensuring you have
a decent terminal and modern fonts installed and configured in your terminal.

### TERM Environment Variable

Atmos uses ANSI color codes. These should work in every modern terminal, including the default terminal shipped with
macOS. You _may_ have to set the `TERM` environment variable to `xterm-256color` for it to work.
This can be persisted in your `~/.bashrc` or `~/.zshrc` file (or the respective RC file of whatever shell is in use).

```shell
export TERM=xterm-256color
```

If you're having any troule, try [iTerm2](https://iterm2.com/) or any other modern day terminal that supports
ANSI characters and fonts.

:::tip Install NerdFonts
To display all icons used by `atmos`, we recommend the use of a Nerd Font, like _Fira Code_.
:::

### NerdFonts

Nerd Fonts are popular fonts that are patched to include icons.

The exact process will depend on your terminal and operating system, but the general idea is to install a font that
includes the necessary glyphs and then configure your terminal.

Go to https://www.nerdfonts.com/ for more information.

:::tip
We recommend the "Fira Code" NerdFont version, which is what all our screenshots are based on.
:::

### Homebrew

#### Homebrew

If you're using Homebrew, you can tap the `homebrew-cask-fonts` repository to install Nerd Fonts.

Paste the following into a macOS Terminal window.

```shell
# Install the NerdFont version of Fira Code
brew install --cask font-fira-code-nerd-font
```

## Next Steps

Now, try one of our Quick Start guides to get started with Atmos

Simple Tutorial
Advanced Tutorial