How to Use the zoxide Command in Linux for Smarter Directory Navigation

Navigating file trees in the Linux terminal using the standard cd command is one of the most repetitive aspects of command-line administration. Moving between deeply nested projects, server log repositories, and configuration paths frequently requires typing long path strings or relying on multiple rounds of tab-completion. While shell aliases and symbolic links offer partial workarounds, they require continuous manual maintenance.

zoxide is a modern, Rust-powered replacement for the traditional cd command that operates across major shells, including Bash, Zsh, and Fish. It monitors your terminal navigation in the background, builds an internal database scored by a “frecency” algorithm (combining frequency and recency), and allows you to jump directly to target directories using simple, partial keywords without needing to specify complete paths.

How zoxide and Frecency Navigation Work

The standard cd command requires an explicit path, such as cd ~/development/workspaces/client-api/src. By contrast, zoxide tracks every directory you visit and assigns weight based on how often and how recently you enter that location. Once a directory has been recorded, you can jump to it from anywhere on the filesystem simply by typing z followed by any distinctive substring.

For example, running z client or z api immediately transports your shell session to ~/development/workspaces/client-api/src. If multiple matching directories exist, zoxide calculates the highest-scoring candidate based on your past activity. If you provide multiple arguments, such as z work api, zoxide refines its lookup to find a directory matching both keywords, minimising false jumps.

Installing zoxide Across Linux Distributions

zoxide is packaged natively in modern package repositories and can also be installed using the universal official script.

Installing on Ubuntu, Debian, and Linux Mint

On Debian-based systems running Ubuntu 22.04 LTS or later, install zoxide using APT:

sudo apt update
sudo apt install zoxide

Installing on Fedora, RHEL, and CentOS

On Fedora and modern Enterprise Linux releases, install the package via DNF:

sudo dnf install zoxide

Installing on Arch Linux and Manjaro

On Arch-based distributions, install zoxide directly from the official repositories using Pacman:

sudo pacman -S zoxide

Universal Installation Script

If your distribution repositories provide an older build, install the latest compiled binary using the official installer:

curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh

Ensure that the resulting binary path (typically ~/.local/bin) is added to your environment’s PATH variable.

Initialising zoxide in Your Shell Configuration

Installing the binary does not immediately replace or hook your shell’s directory navigation. You must initialise zoxide within your shell’s startup script to register the z command wrapper and automatic directory tracking hook.

Configuring Bash

Add the initialisation hook to your ~/.bashrc file:

echo 'eval "$(zoxide init bash)"' >> ~/.bashrc
source ~/.bashrc

Configuring Zsh

For Zsh environments, append the initialisation script to ~/.zshrc:

echo 'eval "$(zoxide init zsh)"' >> ~/.zshrc
source ~/.zshrc

Configuring Fish

For the Fish shell, append the hook to your configuration path:

echo 'zoxide init fish | source' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Navigating Directories with zoxide

Once initialised, continue using your shell normally. As you move through directories using either cd or z, zoxide silently catalogues your movement.

Basic Directory Jumps

After navigating once to a project folder, test the fast-jump syntax:

# Standard navigation registers the path
cd /var/log/nginx

# Return home
cd ~

# Jump straight back using a partial substring
z nginx

Your working directory immediately resolves to /var/log/nginx.

Refining Matches with Multiple Keywords

When working across multiple repositories with overlapping naming structures (such as frontend/src and backend/src), provide multiple arguments to pinpoint the exact destination:

z back src

zoxide evaluates both strings and prioritises the directory matching both tokens.

Interactive Directory Selection with fzf

One of zoxide’s most valuable features is native integration with fzf (the command-line fuzzy finder). When integrated, you can visually inspect matching directories and select your destination using arrow keys or fuzzy search.

Install fzf on Debian or Ubuntu:

sudo apt install fzf

Once fzf is installed, use the interactive query command zi:

zi

An interactive fuzzy search menu launches immediately in your terminal, showing all catalogued directories sorted by frecency score. Type any string to filter the list in real time, press Enter, and your shell switches to that location.

You can also supply an initial filter string directly:

zi project

This restricts the interactive menu to entries containing “project”, allowing instant selection among related workspaces.

Managing and Inspecting the zoxide Database

Because zoxide stores your navigation metrics locally, you can view scores, manually remove obsolete directories, or purge invalid paths.

Viewing Catalogued Scores

To inspect your tracked directories and their corresponding frecency ratings, run the query command:

zoxide query -l -s

The terminal outputs a formatted list showing each directory path alongside its calculated weight.

Removing Obsolete Directories

If a project directory has been deleted, renamed, or moved, you can remove it from zoxide’s database to prevent misdirected jumps:

zoxide remove /path/to/old-directory

To automatically clean up all tracked entries that no longer exist on the filesystem, execute:

zoxide query -l | while read -r dir; do [ ! -d "$dir" ] && zoxide remove "$dir"; done

Replacing Traditional cd Completely

If you prefer to make zoxide your primary navigation utility without typing z, configure the initialisation hook with the --cmd flag to remap cd directly:

# In ~/.bashrc or ~/.zshrc
eval "$(zoxide init bash --cmd cd)"

With this alias active, standard commands like cd .., cd -, and cd /absolute/path continue to behave exactly as expected, while running cd keyword automatically performs an intelligent frecency jump across your recorded filesystem history.