How to Install Atuin on Ubuntu: Magical Shell History with Sync and Search

Atuin rebuilds your shell history around an indexed SQLite database and a fast fuzzy search. Where the default ctrl-r gives you a clumsy single-line reverse search, Atuin opens a full-screen interface where you can filter thousands of past commands instantly and see when, where, and how each one ran.

The reason it feels magical is the context it captures. A traditional history file records only the command text. Atuin also stores the working directory, the exit code, the duration, the hostname, and the session, so you can ask questions like “what did I run in this project last week that failed?”. Add optional end-to-end encrypted sync and your history becomes a portable, queryable resource across every machine you use.

Ubuntu does not ship Atuin in its official archive, so the usual route is the upstream install script plus manual shell wiring. The unofficial deb.griffo.io repository is simpler: it provides a maintained .deb, letting you install Atuin with apt and update it through your normal system upgrades.

What Makes Atuin Special?

  • 🔍 Full-screen fuzzy search — a rich ctrl-r replacement that filters your whole history as you type
  • 🗄️ SQLite-backed database — history stored in a real database instead of a flat file
  • 📌 Command context — every entry keeps its directory, exit status, duration, host, and session
  • 🔐 End-to-end encrypted sync — carry history between machines with the server holding only ciphertext
  • 📊 Built-in statistics — atuin stats reveals your most-used commands and shell habits
  • 🐚 Works with many shells — Bash, Zsh, Fish, and Nushell are all supported
  • ⬆️ Context-aware up arrow — optionally rebind the up key for smarter history recall
  • 📥 Easy import — ingests your existing history on the first run

Why Use the deb.griffo.io Repository?

For Ubuntu users, the deb.griffo.io repository is the cleanest way to run Atuin:

  • Easy installation and updates through APT, Ubuntu’s native package manager
  • Automatic dependency management so required libraries are pulled in for you
  • Releases that follow upstream so you get new features promptly
  • No source builds and no Rust toolchain to babysit
  • Compatibility across supported Ubuntu releases from Jammy through the latest LTS and beyond

Prerequisites

Have the following ready before you start:

  • An Ubuntu system (Jammy 22.04 LTS, Noble 24.04 LTS, or newer)
  • A user with sudo privileges
  • curl installed (sudo apt install curl if needed)
  • A supported interactive shell such as Bash or Zsh

Step 1: Add the deb.griffo.io Repository

Add the key and the repository with the commands below:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

A quick walkthrough:

  1. install -d creates /etc/apt/keyrings with safe permissions for the signing key
  2. curl … gpg --dearmor downloads the key and stores it in the format APT verifies against
  3. echo … tee writes the source line, letting lsb_release -sc fill in your Ubuntu codename
  4. apt update refreshes the package metadata so Atuin can be installed

Step 2: Update the Package List

If you skipped the final command above, run it now:

sudo apt update

Step 3: Install Atuin

Install Atuin through APT:

sudo apt install atuin

APT resolves dependencies and installs the atuin binary.

Step 4: Verify the Installation

Confirm the version:

atuin --version

You should see output similar to:

atuin 18.4.0

The binary is installed now, but Atuin will not manage your history until you add its shell hook — covered next.

Getting Started with Atuin

Atuin becomes useful only after you enable its shell integration. Here is the setup path.

Import Your Existing History First

Before enabling the hook, pull your current history into Atuin so nothing is lost:

atuin import auto

The auto argument detects your shell and imports from the correct history file. You can also be explicit with atuin import bash or atuin import zsh.

Enable Shell Integration (Required)

Atuin activates by adding an init line to your shell startup file.

For Bash, append this to ~/.bashrc:

eval "$(atuin init bash)"

For Zsh, add this to ~/.zshrc:

eval "$(atuin init zsh)"

Reload the shell so the hook takes effect:

exec bash

Now ctrl-r opens Atuin’s search. Atuin binds the up arrow by default; if you prefer to keep the native up-arrow behaviour, disable that binding:

eval "$(atuin init bash --disable-up-arrow)"

Searching from Scripts

The interactive ctrl-r UI is the main way to search, but atuin search also works from the command line and in scripts:

# Search for commands mentioning "kubectl"
atuin search kubectl

# The last 10 commands run in the current directory
atuin search --cwd . --limit 10

# Commands that failed with a non-zero exit code
atuin search --exit 1

# Restrict to a time window
atuin search --after "1 week ago" --before "1 day ago" apt

Within the interactive view you can cycle filter modes to limit results to the current directory, host, or session.

Understanding Your Habits

Atuin can summarise how you use the terminal:

# Most-used commands and totals
atuin stats

# Stats for a specific window
atuin stats last week

Optional Encrypted Sync

To keep history consistent across machines, register and sync:

# Register an account
atuin register -u <username> -e <email>

# Push local history to the server
atuin sync

# On a second machine, log in and pull it down
atuin login -u <username>
atuin sync

Because sync is end-to-end encrypted with a key held only on your devices, the server never sees your commands in plaintext. Self-hosting the sync server is also supported if you want full control.

Keeping Atuin Updated

As a managed package, Atuin updates with the rest of your system:

sudo apt update && sudo apt upgrade

Each upgrade installs the latest packaged release without any manual steps.

Other Tools from deb.griffo.io

The repository packages a wide range of terminal tools for Ubuntu:

  • zoxide — a smarter cd that ranks directories by use
  • Starship — a fast, configurable prompt for any shell
  • fzf — a fuzzy finder that complements history search
  • Nushell — a structured-data shell Atuin integrates with

Troubleshooting

Package Not Found

If APT cannot see the atuin package:

  1. Re-run sudo apt update to refresh the index
  2. Confirm your Ubuntu release is supported (Jammy, Noble, or newer)
  3. Check the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list

GPG or Key Errors

If APT reports a signature or key issue, re-import the key:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

ctrl-r Does Not Open Atuin

If ctrl-r still shows Ubuntu’s default reverse search, the shell hook is not active. Verify the init line and reload:

grep atuin ~/.bashrc
exec bash

Place eval "$(atuin init bash)" toward the end of ~/.bashrc, after any other tool that binds ctrl-r, so Atuin claims the keybinding last.

Uninstalling

Remove the init line from your shell config, then remove the package:

sudo apt remove atuin

To detach the repository as well:

sudo rm /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Your history database at ~/.local/share/atuin stays in place unless you delete it yourself.

Conclusion

Atuin transforms an afterthought — shell history — into a searchable, context-aware database, with optional encrypted sync that carries it across every machine you touch. On Ubuntu, the deb.griffo.io repository makes it a one-line apt install atuin, and future updates ride along with your usual apt upgrade.

Install it, run atuin import auto, add the init line, reload your shell, and press ctrl-r. After a day of using it, the old history file feels unusable by comparison.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream Atuin project.