# Installation

Simply run the installation script and that will walk you through installing
Atuin:

```shell
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh
```

After installing, the script runs `atuin setup`. Setup hooks Atuin into your
shells, imports your shell history, and offers to set up a sync account.

<VHSTape title="The install script downloading Atuin, then its setup: keeping shell history, Ctrl-R and the up arrow, turning sync off, and importing 230 commands from zsh.">
  Env DOCS_NEW_USER "1"
  Set FontSize 20
  Set Height 800
  Set TypingSpeed 35ms
  Type "curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh"
  Sleep 500ms
  Enter
  Wait+Screen@2m /Continue/
  Sleep 2s
  Down@400ms 3
  Sleep 500ms
  Left
  Sleep 1s
  Down
  Sleep 500ms
  Enter
  Wait+Screen@30s /already here/
  Sleep 1.5s
  Down
  Sleep 500ms
  Enter
  Wait+Screen@1m /is ready/
  Sleep 4s
</VHSTape>

This will install a binary to `~/.atuin/bin`.

> [!TIP]
>
> You can skip interactive install with the `--non-interactive` flag:
>
> ```shell
> curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh \
>   | sh -s -- --non-interactive
> ```
>
> Without prompts, the script runs `atuin setup --yes --no-import`, which sets
> Atuin up without asking and doesn't import your history.
>
> Anything else you pass goes to [`atuin setup`](/reference/cli/setup/), which
> starts from those choices. For example, to leave the up arrow to your shell and
> keep everything on this machine:
>
> ```shell
> curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh \
>   | sh -s -- --no-up-arrow --sync off
> ```
>
> You can run `atuin setup` again at any time to change what it set up.

## Upgrade

Run `atuin update`, and if that command isn't available, run the install script
again.

> [!TIP] Rate Limits
> If GitHub's API rate limit prevents the update, set `ATUIN_GITHUB_TOKEN` to a
> GitHub token. For example, if you use the GitHub CLI:
>
> ```shell
> ATUIN_GITHUB_TOKEN="$(gh auth token)" atuin update
> ```

:::caution[Note]

If you used a package manager to install Atuin, then you should also use your
package manager to update Atuin.

:::

### Moving to `~/.atuin`

Older versions of Atuin stored data in `~/.config/atuin` (or
`$XDG_CONFIG_HOME/atuin`) and `~/.local/share/atuin` (or
`$XDG_DATA_HOME/atuin`). While `ATUIN_HOME` is unset, Atuin still looks for
data in the old locations when it doesn't find it in `~/.atuin`, so an older
install keeps working as it is.

To move to the new layout, run these commands in Bash, Zsh or fish. Adjust the
paths if you set `XDG_CONFIG_HOME` or `XDG_DATA_HOME`.

Stop the daemon, and turn autostart off for now:

```sh
atuin config set daemon.autostart false
atuin daemon stop
```

Make sure `~/.atuin` exists:

```sh
mkdir -p ~/.atuin
```

Check whether you have any AI-related files in `~/.atuin`:

```sh
ls ~/.atuin | grep -Fxe permissions.ai.toml -e skills
```

If you do, follow this section first:

<details>
<summary>Migrating home-scoped AI config</summary>

In older installs, `permissions.ai.toml` and `skills` in `~/.atuin` apply to
your home directory. In newer installs, they apply _globally_. Whether
`~/.atuin/config.toml` exists decides which: if it does, these items are
global.

Before you move your `config.toml` to `~/.atuin`, review the AI files already
in `~/.atuin`, especially `permissions.ai.toml`. Leave anything you're fine
with applying globally, which is close to applying to your whole home directory
anyway. Delete anything else, or move it into `~/subdir/.atuin/` for each
subdirectory it should apply to.

Then check whether any AI items appear in both `~/.atuin` and
`~/.config/atuin`:

```sh
ls ~/.atuin ~/.config/atuin | grep -Fxe permissions.ai.toml -e skills | \
    sort | uniq -d
```

Those in `~/.atuin` shadow those in `~/.config/atuin`. Merge any you still want
into `~/.atuin`.

</details>

Move your config:

```sh
cd ~/.config/atuin && mv -n $(ls | grep -Fxe config.toml -e server.toml \
    -e themes -e skills -e permissions.ai.toml) ~/.atuin/
```

Move your data:

```sh
[ -e ~/.atuin/data ] && echo 'error: destination exists' || \
    mv -n ~/.local/share/atuin ~/.atuin/data
```

Turn daemon autostart back on, if you had it on before:

```sh
atuin config set daemon.autostart true
```

## Uninstall

If you'd like to uninstall Atuin, please check out [the uninstall page](/help/uninstall/).

TODO avoid this section

## Manual Installation

We **do not recommend** using alternative installation methods, but we try our
best to support them:

Atuin requires a recent Rust toolchain. Distribution package managers often
ship an older Rust, so it's best to use [rustup](https://rustup.rs/) to set up
an up-to-date toolchain, then you can run:

```shell
cargo install atuin --locked
```

```shell
brew install atuin
```

Atuin is also available in [MacPorts](https://ports.macports.org/port/atuin/):

```shell
sudo port install atuin
```

Atuin is also installable using [mise](https://github.com/jdx/mise):

```shell
mise use -g atuin@latest
```

This repository is a flake, and can be installed using `nix profile`:

```shell
nix profile install "github:atuinsh/atuin"
```

Linux builds of `main` are cached on [Cachix](https://atuin.cachix.org). Run
`cachix use atuin` first to download them instead of building from source.

Atuin is available in the Arch Linux [extra
repository](https://archlinux.org/packages/extra/x86_64/atuin/):

```shell
pacman -S atuin
```

Atuin is available in the Termux package repository:

```shell
pkg install atuin
```

Atuin is installable from github-releases directly:

```shell
# line 1: `atuin` binary as command, from github release, only look at .tar.gz files (excluding server), use the `atuin` file from the extracted archive
# line 2: setup at clone(create init.zsh, completion)
# line 3: pull behavior same as clone, source init.zsh
zinit ice as"command" from"gh-r" bpick"atuin-*.tar.gz~*server*" mv"atuin*/atuin -> atuin" \
    atclone"./atuin init zsh > init.zsh; ./atuin gen-completions --shell zsh > _atuin" \
    atpull"%atclone" src"init.zsh"
zinit light atuinsh/atuin
```

Atuin is available on WinGet:

```shell
winget install -e Atuinsh.Atuin
```

Then, in a new shell, run `atuin setup`. Setup adds Atuin to the profiles of
both PowerShell 7 and Windows PowerShell.

Atuin builds on the latest stable version of Rust, and we make no
promises regarding older versions. The minimum supported version is set by
`rust-version` in the workspace
[`Cargo.toml`](https://github.com/atuinsh/atuin/blob/main/Cargo.toml)
(currently 1.98.0). We recommend using [rustup](https://rustup.rs/).

```shell
git clone https://github.com/atuinsh/atuin.git
cd atuin
cargo install --path crates/atuin --locked
```

:::caution[Note]

After installing the binary another way, run `atuin setup` to hook Atuin into
your shells. Setup also imports your shell history and offers to set up sync.
For Nushell, xonsh, and zsh plugin managers, see
[Installing the shell plugin](#installing-the-shell-plugin).

:::

:::caution[Note]

Package managers may provide you with an outdated version of Atuin. The
installation script we provide keeps atuin up-to-date and allows you to update
Atuin through an `atuin update` command.

:::

### Installing the shell plugin

Once the binary is installed, the shell plugin needs installing. For zsh,
bash, fish, and PowerShell, `atuin setup` installs it for you, and the install
script runs `atuin setup`. After installing, remember to restart your shell.

To hook only some shells and change nothing else, pass `--only` and name the
shells with `--shells`. For example, this command hooks zsh and fish:

```shell
atuin setup --only --shell-history --shells zsh,fish
```

Run setup, which adds `eval "$(atuin init zsh)"` to `$ZDOTDIR/.zshrc`, or to
`~/.zshrc` when `ZDOTDIR` isn't set:

```shell
atuin setup --only --shell-history --shells zsh
```

If you use a plugin manager, load Atuin with it instead.

```shell
# if you _only_ want to install the shell-plugin, do this; otherwise look above for a "everything via zinit" solution
zinit load atuinsh/atuin
```

```shell
antigen bundle atuinsh/atuin@main
```

```shell
antidote install atuinsh/atuin
```

Atuin works best in bash when using [ble.sh](https://github.com/akinomyoga/ble.sh) >= 0.4.

With ble.sh (>= 0.4) installed and loaded in `~/.bashrc`, run setup, which adds
`eval "$(atuin init bash)"` to the end of your `~/.bashrc`:

```shell
atuin setup --only --shell-history --shells bash
```

[bash-preexec](https://github.com/rcaloras/bash-preexec) can also be used, but you may experience
some minor problems with the recorded duration and exit status of some commands.

:::caution[Please note]

bash-preexec currently has [an issue](https://github.com/rcaloras/bash-preexec/issues/115) where it will stop
honoring `ignorespace`. While Atuin will ignore commands prefixed with
whitespace, they may still end up in your bash history. Please check your
configuration! All other shells don't have this issue.

To use `atuin < 18.10.0` in `bash < 4` with bash-preexec, the option
`enter_accept` needs to be turned on (which is so by default). There is no
restriction in the latest version of Atuin (>= 18.10.0).

bash-preexec can't properly invoke the `preexec` hook for subshell commands
`(...)`, function definitions `func() { ...; }`, empty for-in-statements `for
i in; do ...; done`, etc., so those commands and duration may not be recorded
in the Atuin's history correctly.
:::

As of Atuin 18.18.0, `atuin init bash` will automatically load bash-preexec if no other
preexec backend has been loaded (ble.sh or an external copy of bash-preexec). To use the
built-in copy, run setup, which adds `eval "$(atuin init bash)"` to your `~/.bashrc`:

```shell
atuin setup --only --shell-history --shells bash
```

To disable the built-in copy, pass `ATUIN_NO_BUILTIN_PREEXEC=1` to `atuin init` in your
`~/.bashrc`, e.g.:

```shell
eval "$(ATUIN_NO_BUILTIN_PREEXEC=1 atuin init bash)"
```

If you prefer, you can also download and install bash-preexec separately:

```shell
curl https://raw.githubusercontent.com/rcaloras/bash-preexec/master/bash-preexec.sh -o ~/.bash-preexec.sh
echo '[[ -f ~/.bash-preexec.sh ]] && source ~/.bash-preexec.sh' >> ~/.bashrc
```

Then run setup, which adds Atuin to the end of your `~/.bashrc`, after
bash-preexec:

```shell
atuin setup --only --shell-history --shells bash
```

Run setup, which adds an `is-interactive` block that runs
`atuin init fish | source` to your `~/.config/fish/config.fish` file:

```shell
atuin setup --only --shell-history --shells fish
```

Run in _Nushell_:

```shell
mkdir ~/.atuin/
atuin init nu | save ~/.atuin/init.nu
```

Add to `config.nu`:

```shell
source ~/.atuin/init.nu
```

<details>
<summary>Optional: Atuin pty-proxy</summary>

pty-proxy is a lightweight pty proxy that renders the Atuin popup over
your previous output, restoring it when closed — no clearing, no
fullscreen. To use pty-proxy with Nushell, generate the init script:

```shell
mkdir ~/.atuin/
atuin pty-proxy init nu | save -f ~/.atuin/pty-proxy-init.nu
```

Then source it as early as possible in your `config.nu`, _before_
the regular atuin init:

```shell
source ~/.atuin/pty-proxy-init.nu
source ~/.atuin/init.nu
```

Nushell's `source` command requires a static file path, so you must
pre-generate both files.

</details>

Add

```shell
execx($(atuin init xonsh))
```

to the end of your `~/.xonshrc`

Run setup, which adds `atuin init powershell | Out-String | Invoke-Expression`
to the end of your PowerShell profile:

```shell
atuin setup --only --shell-history --shells powershell
```

On Windows, setup writes to the profiles of both PowerShell 7 and Windows
PowerShell, in your Documents folder. Elsewhere, setup writes to
`~/.config/powershell/Microsoft.PowerShell_profile.ps1`.