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

zoxide is a smarter cd command for your terminal, written in Rust and inspired by tools like z and autojump. It remembers the directories you visit and ranks them by “frecency”, a blend of frequency and recency, so instead of typing long paths you can jump to a directory with a single keyword. Type z proj and land in the project you were in yesterday, wherever it happens to live.

zoxide is not part of the official Debian archive, so installation typically means the upstream install script, a cargo install, or a manual binary download, each with its own update burden.

The unofficial deb.griffo.io repository packages zoxide as a standard Debian .deb served over APT, so you install it and keep it current with the tooling you already use, then add one line to your shell config to switch it on.

What Makes zoxide Special?

  • 🧠 Frecency ranking - Learns which directories you use most and prioritises them automatically.
  • ⚡ Instant jumps - z keyword takes you to the best-matching directory in one command.
  • 🖥️ Interactive selection - zi opens an fzf-powered picker when several directories match.
  • 🐚 Works everywhere - Supports Bash, Zsh, Fish, PowerShell, Nushell and Elvish.
  • 🚀 Rust performance - A tiny, fast binary with negligible shell startup overhead.
  • 🔄 Drop-in cd replacement - Alias it to cd and keep all your existing habits.
  • 🗃️ Portable database - Your history lives in a simple, queryable database you can edit.
  • 🔌 Zero-config start - Works out of the box after a single shell init line.

Why Use the deb.griffo.io Repository?

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

Prerequisites

Before you begin, make sure you have:

  • A Debian-based system (Bookworm 12, Trixie 13, or Sid)
  • sudo privileges
  • curl installed (sudo apt install curl if needed)

Step 1: Add the deb.griffo.io Repository

Add the signing 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

What each command does:

  1. Create the keyrings directory - ensures /etc/apt/keyrings exists with proper permissions.
  2. Install the GPG key - downloads the key and de-armours it into a dedicated keyring for verification.
  3. Add the repository - writes a signed-by source line, using lsb_release -sc to detect your Debian codename.
  4. Update the package list - refreshes APT so it knows about the new packages.

Step 2: Update the Package List

If you skipped the last line, refresh the index now:

sudo apt update

Step 3: Install zoxide

Install zoxide with APT:

sudo apt install zoxide

APT installs the single zoxide binary system-wide.

Step 4: Verify the Installation

The binary is zoxide. Check the version:

zoxide --version

You should see output similar to:

zoxide 0.9.6

At this point the binary is installed, but zoxide is not active until you add its init line to your shell.

Getting Started with zoxide

Enabling the Shell Integration

zoxide needs one init line in your shell configuration. It generates the necessary functions and hooks at shell startup. For Bash, add this to the end of ~/.bashrc:

eval "$(zoxide init bash)"

For Zsh, add the equivalent to ~/.zshrc:

eval "$(zoxide init zsh)"

For Fish, add to ~/.config/fish/config.fish:

zoxide init fish | source

Reload your shell (or open a new terminal) and zoxide starts recording the directories you visit.

Using z to Jump Around

Once active, z is your navigation command:

# cd into a directory to teach zoxide about it
cd ~/projects/website/src

# Later, jump straight back with a keyword
z website

# Match on multiple keywords for precision
z web src

# Jump to a subdirectory of the current best match
z website assets

zoxide ranks candidates by frecency, so the more you visit a directory, the more reliably a short keyword takes you there.

Interactive Selection with zi

When a keyword is ambiguous, use zi to pick from a menu. If fzf is installed, this becomes a fuzzy-searchable interactive list:

# Open an interactive picker filtered by keyword
zi project

# Open the full interactive list
zi

Replacing cd Entirely

If you want zoxide to take over navigation completely, initialise it with the --cmd cd flag so that cd itself gains zoxide’s smarts:

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

Now cd keyword behaves like z keyword, while cd path still works exactly as before.

Managing the Database

zoxide keeps a queryable database of your directory history:

# List tracked directories with their scores
zoxide query --list --score

# Manually add a directory
zoxide add /opt/deploy/current

# Remove a directory that no longer exists
zoxide remove /old/path

Keeping zoxide Updated

Because zoxide came from APT, updates arrive with your regular system upgrades:

sudo apt update && sudo apt upgrade

When deb.griffo.io publishes a newer zoxide, apt upgrade installs it automatically.

Other Tools from deb.griffo.io

The repository packages many tools that complement zoxide:

  • fzf - the fuzzy finder that powers zoxide’s interactive zi picker.
  • eza - a modern ls replacement to run once you have jumped.
  • Starship - a fast, customisable prompt that pairs well with a snappy shell.
  • Atuin - magical shell history to complement smarter directory navigation.

Troubleshooting

GPG or Key Errors

If APT reports an unsigned repository or an invalid key, re-import 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 find zoxide:

  1. Re-run sudo apt update after adding the repository.
  2. Confirm your release is supported (Bookworm, Trixie, or Sid).
  3. Check the source list: cat /etc/apt/sources.list.d/deb.griffo.io.list.

The z Command Is Not Found

If typing z gives “command not found”, the shell init line has not been loaded. This is the single most common issue, since installing the binary alone does not activate the z function:

# Confirm the init line is present in your shell config
grep -n "zoxide init" ~/.bashrc

Make sure eval "$(zoxide init bash)" is there and appears after any prompt or framework setup, then open a new terminal.

Uninstalling

Remove zoxide with:

sudo apt remove zoxide

To also drop 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

Remember to remove the zoxide init line from your shell config as well.

Conclusion

Installing zoxide from deb.griffo.io gives Debian users a smarter cd without a Rust toolchain or a manual install script. After a single shell init line, z keyword replaces long, repetitive cd commands, and zi gives you an interactive fallback when matches are ambiguous.

zoxide learns your habits and quietly speeds up one of the most frequent things you do in a terminal. Keeping it current is now just another 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.