TL;DR:

  • zoxide is a smart cd replacement that tracks your most-visited directories and lets you jump to them with fuzzy partial matching — z proj goes straight to /Users/you/code/client/project-dashboard if that’s where you spend most of your time
  • It works in bash, zsh, fish, and most other shells, and pairs naturally with fzf for interactive directory selection when the fuzzy match is ambiguous
  • Installs in under a minute and then gets out of the way — this is one of those tools you stop noticing because it just works

Here’s something that probably sounds trivial until you think about how often you do it: navigating to directories. As a developer, you cd into the same handful of directories dozens of times a day. Your main project, the config directory, that one deeply nested thing you always have to look up. cd with tab completion is fine, but it still requires you to type enough of the path to disambiguate. zoxide asks: what if the shell remembered where you’ve been and let you jump there with two or three characters?

That’s the whole thing. It’s not complicated. But once it’s installed, going back to standard cd feels like going back to a world without tab completion.

How It Works

zoxide maintains a database of directories you’ve visited, scored by frequency and recency. The more often you visit a directory and the more recently you’ve been there, the higher its score. When you type z <query>, zoxide looks for the highest-scoring directory that matches your query as a substring. It doesn’t require you to type from the beginning of the path — any part of any directory name in the path will match.

So if you’ve been working in /home/alice/code/acme-corp/frontend/src/components, then z components will take you straight there. z acme front will match on both “acme-corp” and “frontend” in the path. The scoring means frequently visited directories bubble up automatically — you don’t need to explicitly bookmark anything.

Installing zoxide

# macOS
brew install zoxide

# Ubuntu/Debian
sudo apt install zoxide

# Arch
sudo pacman -S zoxide

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

After installing the binary, add the shell integration to your config:

# bash — add to ~/.bashrc
eval "$(zoxide init bash)"

# zsh — add to ~/.zshrc
eval "$(zoxide init zsh)"

# fish — add to ~/.config/fish/config.fish
zoxide init fish | source

Restart your shell, and that’s it. zoxide installs as z by default. Your database starts empty and fills up as you navigate normally — within a day of normal use it’ll have enough data to be useful.

The zi Command (Interactive Mode)

On its own, z <query> is great when you know roughly where you’re going. But what about when the query matches multiple directories? That’s where zi comes in — it’s z with interactive selection via fzf.

zi acme

If you’ve worked in several “acme” directories, zi opens a fzf picker showing all matching options with their scores, and you select the one you want. This is the command you reach for when you want to explore rather than jump directly.

If fzf isn’t installed, zi falls back to a numbered list. But fzf is worth installing separately anyway — it upgrades shell history search (Ctrl+R) and file completion at the same time.

Replacing cd Entirely

Some people keep both z and cd — use z for frequently visited directories, cd for one-off navigation. Others prefer to replace cd completely:

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

This makes cd behave like zoxide while still using the familiar command name. The original builtin cd is still available if you need it. Whether you prefer this or keeping z as a separate command is personal preference — both work well.

How the Ranking Works

The scoring algorithm is worth understanding because it determines what z query returns when there are multiple matches.

zoxide uses a “frecency” score — a combination of frequency (how often you visit a directory) and recency (how recently). The exact formula is:

  • Each visit adds to the directory’s count
  • Directories visited recently are weighted more heavily than older visits
  • The score decays over time, so stale directories gradually drop in ranking

In practice, this means:

  • If you start a new project today, it’ll start ranking highly for its own directory name within hours
  • If you worked on something three months ago and haven’t touched it since, it’ll rank below your current active projects even if it was visited more total times

You don’t need to manage the database manually. It just adapts to how your work changes.

Useful Commands

z <query>     # Jump to best matching directory
zi <query>    # Interactive picker (requires fzf)
z -           # Jump to previous directory (like cd -)
z ..          # Goes up one directory (standard behaviour)

# Database management
zoxide query <query>        # Show what z would jump to without jumping
zoxide query --list         # List all directories in the database
zoxide remove /path/to/dir  # Remove a directory from the database
zoxide import --from autojump ~/.autojump/data  # Migrate from autojump

The zoxide query --list command is handy when you want to see what’s in your database, particularly in a new environment where you haven’t built up history yet and want to verify it’s tracking correctly.

Migrating from autojump or z

If you’ve been using autojump or the z shell script (both do similar things), zoxide can import your existing database:

# From autojump
zoxide import --from autojump ~/.autojump/data

# From z (the shell script)
zoxide import --from z ~/.z

This means you don’t lose your existing directory history when switching — your most-visited directories will already rank highly from day one.

Pairing with Your Existing Setup

zoxide works particularly well alongside a few other tools that you might already have:

fzf — for the zi interactive mode. If you’ve installed fzf for Ctrl+R history search, zi is immediately available.

starship — the cross-shell prompt that can show the current directory path, git status, and more. zoxide navigation changes where you are, starship shows you where you are. Together they make terminal navigation feel fast and clear.

fd — a fast file finder. When you need to locate a file within a directory you’ve jumped to with zoxide, fd <filename> is much faster than find.

None of these require configuration to work together — they’re all independent tools that happen to complement each other naturally.

Is It Worth It?

Honestly: yes, and the set-up cost is under three minutes. The payoff is that every project hop for the rest of your career is slightly faster. That compounds. The cognitive overhead of “where was that directory again, I need to tab-complete down three levels” vanishes.

The people who stop using zoxide after installing it are usually those who used it for a day before the database had enough history to be useful, decided it didn’t work, and uninstalled it. Give it a week. By the end of that week, your most frequently visited directories will jump reliably on two or three keystrokes, and going back to plain cd will feel like a step backwards.

One tool, one shell config line, done. That’s the whole migration.