How to Install zoxide on Ubuntu: A Smarter cd Command for Your Terminal

zoxide is a smarter cd command for your terminal. Written in Rust and building on the ideas behind z and autojump, it tracks the directories you visit and ranks them by “frecency”, frequency combined with recency, so a single keyword can teleport you across your filesystem. Instead of cd ~/work/clients/acme/backend, you just type z acme and you are there.

Ubuntu does not ship zoxide in its archive, so the common installation methods are the upstream install script, cargo install, or a hand-downloaded binary, all of which leave updates to you.

The unofficial deb.griffo.io repository provides zoxide as a native Ubuntu .deb over APT. You install it with apt, add one line to your shell config to activate it, and future updates arrive with your normal system upgrades.

What Makes zoxide Special?

  • 🧠 Frecency ranking - Automatically favours the directories you visit most and most recently.
  • ⚡ Instant jumps - z keyword moves you to the best-matching directory in a single command.
  • 🖥️ Interactive selection - zi shows an fzf-backed picker when a keyword matches several places.
  • 🐚 Works everywhere - Bash, Zsh, Fish, PowerShell, Nushell and Elvish are all supported.
  • 🚀 Rust performance - A small, fast binary that adds almost nothing to shell startup.
  • 🔄 Drop-in cd replacement - Alias it over cd and keep every habit you already have.
  • 🗃️ Portable database - A simple database you can query, edit and back up.
  • 🔌 Zero-config start - One init line and it just works.

Why Use the deb.griffo.io Repository?

  • Easy installation and updates through APT.
  • Automatic dependency management provided by the Ubuntu packaging.
  • Always tracks upstream releases so you get the newest zoxide features.
  • No compiling from source and no Rust or Cargo toolchain to maintain.
  • Works across supported Ubuntu releases, with the codename detected automatically.

Prerequisites

Make sure you have:

  • An Ubuntu system (Jammy 22.04 LTS, Noble 24.04 LTS, or newer)
  • sudo privileges
  • curl installed (sudo apt install curl if needed)

Step 1: Add the deb.griffo.io Repository

Register the key and repository source:

# 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

Step by step:

  1. Create the keyrings directory - guarantees /etc/apt/keyrings exists with sensible permissions.
  2. Install the GPG key - downloads and de-armours the key into a dedicated keyring so APT can verify signatures.
  3. Add the repository - writes a signed-by source line, with lsb_release -sc filling in your Ubuntu codename.
  4. Update the package list - refreshes APT’s package index.

Step 2: Update the Package List

If you did not run the last command above, do it now:

sudo apt update

Step 3: Install zoxide

Install with APT:

sudo apt install zoxide

APT installs the single zoxide binary across the system.

Step 4: Verify the Installation

The binary is zoxide. Confirm the version:

zoxide --version

You should see something like:

zoxide 0.9.6

The binary is now installed, but zoxide only becomes useful once you add its init line to your shell, covered next.

Getting Started with zoxide

Activating zoxide in Your Shell

zoxide relies on a single init line that generates its shell functions at startup. Ubuntu defaults to Bash, so add this to the end of ~/.bashrc:

eval "$(zoxide init bash)"

If you use Zsh, add the same idea to ~/.zshrc:

eval "$(zoxide init zsh)"

And for Fish, edit ~/.config/fish/config.fish:

zoxide init fish | source

Open a new terminal afterwards. From then on, zoxide silently records the directories you cd into.

Replacing cd from the Start

Many people prefer zoxide to take over cd outright rather than learning a new z command. Initialise it with --cmd cd to do exactly that:

# In ~/.bashrc instead of the plain init line:
eval "$(zoxide init --cmd cd bash)"

Now cd keyword jumps by frecency while cd ./relative/path still works normally, so there is nothing new to remember.

Jumping with z

If you keep the default command, z is how you navigate:

# Seed the database by visiting a directory
cd /var/www/acme/backend

# Jump back later from anywhere
z backend

# Combine keywords to disambiguate
z acme backend

# Move into a child of the matched directory
z acme config

Interactive Picking with zi

When several directories match a keyword, zi lets you choose. With fzf installed it becomes a fuzzy, interactive menu:

# Filter interactively by keyword
zi acme

# Browse the whole ranked list
zi

Inspecting and Editing the Database

zoxide’s history is a database you can query and prune:

# Show tracked paths with scores
zoxide query --list --score

# Add a path explicitly
zoxide add /srv/deploy/current

# Drop a stale entry
zoxide remove /nonexistent/path

Keeping zoxide Updated

zoxide follows your normal Ubuntu update cycle:

sudo apt update && sudo apt upgrade

When deb.griffo.io ships a newer zoxide, apt upgrade installs it with your other packages.

Other Tools from deb.griffo.io

The repository packages several tools that go hand in hand with zoxide:

  • fzf - the fuzzy finder that drives zoxide’s interactive zi mode.
  • eza - a modern, colourful ls to reach for after jumping.
  • Starship - a fast, minimal prompt for a snappier shell.
  • Atuin - searchable, synced shell history to round out the setup.

Troubleshooting

GPG or Key Errors

If APT flags the repository as unsigned or the key as invalid, re-add it:

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

Package Not Found

If APT cannot locate zoxide:

  1. Re-run sudo apt update after adding the repository.
  2. Verify your Ubuntu release is supported (Jammy, Noble, or newer).
  3. Inspect the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list.

z Works but Never Learns New Directories

If z is available but always jumps to the same few places, zoxide may not be hooking into your directory changes, usually because the init line sits before the shell framework that later overrides the prompt hook. Move the init line to the very end of your config:

grep -n "zoxide init" ~/.bashrc

Ensure eval "$(zoxide init bash)" is the last relevant line, then reopen your terminal so the hook is registered correctly.

Uninstalling

Remove zoxide with:

sudo apt remove zoxide

To also remove the repository and key:

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

Do not forget to delete the zoxide init line from your shell config.

Conclusion

On Ubuntu, deb.griffo.io turns zoxide into a proper APT package, no Rust toolchain, no install script, no manual updates. One init line later, z keyword (or a supercharged cd) replaces the tedium of typing long paths, with zi as an interactive fallback.

zoxide quietly learns where you work and shaves seconds off navigation dozens of times a day. Keeping it current is simply part of your usual apt upgrade.

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 zoxide project.