What Is Zoxide?

I used to navigate my filesystem one directory at a time. cd ~/Projects, then ls, then cd websites, then ls, then cd jeffbaileyblog, then ls, then cd hugo. Every trip to a familiar directory cost me four or five commands. Tab-completion helped a little, but I still had to remember the path.

Then I installed zoxide, and cd started reading my mind.

What zoxide actually is

Zoxide is a smarter replacement for cd. It watches where you go in your terminal, ranks those directories by how often and how recently you visit them, and lets you jump to any of them by typing a fragment of the path.

Instead of cd ~/Projects/websites/jeffbaileyblog/hugo, I type z hugo. Zoxide remembers that I live in that directory most days, and it takes me there.

Ajeet D’Souza wrote it in Rust. It’s a single binary with no runtime dependencies. It works in bash, zsh, fish, PowerShell, nushell, and a handful of others. You install it once, add a line to your shell config, and z replaces cd for most of your navigation.

The word that matters here is “frecency,” a blend of frequency and recency. Zoxide doesn’t just track your most-visited directories. It weights recent visits more heavily than old ones, so the ranking adapts as your work shifts. The directory you lived in last quarter fades. The one you’ve been in all week rises to the top.

Why zoxide exists

Traditional cd treats every navigation as a fresh problem. You tell it exactly where to go, and it goes. It has no memory of your six visits today to ~/Projects/websites/jeffbaileyblog/hugo. The seventh time, you still type it out or tab-complete through it.

That’s fine for directories you visit once. It’s wasteful for the ten or so directories you actually live in.

Zoxide started as a Rust rewrite of earlier tools. z came first, written in shell by Rupa Vedula. Then autojump in Python, and fasd as another shell-based variant. Each one had the same idea: the shell should learn where you go, and jumping should take one short command.

Zoxide took that idea and made it fast and portable. Rust gave it near-instant startup (a cold z resolves in microseconds on my machine). The single-binary distribution removed the dependency headaches that plagued the Python and shell versions. And the interface got simpler: one command (z) and one interactive variant (zi).

The mental model: frecency as your shell’s intuition

Zoxide’s core idea is frecency. Every time you cd into a directory, zoxide bumps that directory’s score. Over time, active directories float to the top of the ranking. Dormant ones sink.

The ranking is the whole trick. When I type z hugo, zoxide scans its database for every directory whose path contains “hugo,” then returns the one with the highest frecency score. That’s almost always the one I want, because I go there daily.

Zoxide’s algorithm decays old visits using a simple formula. A visit today counts more than a visit yesterday, which counts more than a visit last month. The decay is gradual, so a directory you used heavily last quarter still shows up, but a directory you’ve been hitting all week outranks it.

This matches how humans actually use filesystems. I don’t visit 500 directories evenly. I cycle through ten or fifteen active projects, with the mix shifting every few weeks. Frecency captures that pattern directly.

How the commands work

Zoxide exposes two main commands: z for non-interactive jumps, and zi for interactive selection.

z: jump to the best match

z fragment searches your frecency database and jumps to the top-scoring directory that matches. You can pass multiple fragments to narrow further:

z hugo              # jump to the best "hugo" directory
z blog what-x       # jump to a directory matching both "blog" and "what-x"
z proj web          # disambiguate between multiple projects

Fragments don’t have to be contiguous in the path. z proj web matches ~/Projects/websites because both words appear in order. That matters when you have similar directory names across several roots.

If you type z with no argument, zoxide takes you home. If you type z - (a single dash), it takes you to the previous directory, just like cd -.

zi: interactive mode

zi opens an fzf-backed picker showing your top-ranked directories. You type to filter the list, arrow-key through the matches, and hit enter to jump.

I use zi when my query is ambiguous. If I type z config and zoxide sends me to the wrong config directory, I run zi config next, see the full list, and pick the right one. After that, zoxide learns my preference (the selected directory’s frecency bumps up) and z config goes to the correct place next time.

Zoxide and fzf: two filters that compose

Zoxide and fzf solve adjacent problems. Fzf filters any list interactively. Zoxide maintains a ranked list of directories. Put them together and you get the best of both: a small, relevant list of your most-used directories, filtered interactively.

This is what zi does under the hood. It asks zoxide for the ranked list, then pipes that list into fzf for picking. The mental model composes cleanly:

• Zoxide knows where you go.
• Fzf lets you pick from a list.
• Together they let you pick from where you go.

That’s why zoxide lists fzf as an optional dependency. Without fzf, zi falls back to a simpler picker. With fzf, zi feels like the fuzzy finder you’d build for shell navigation if you were designing one from scratch.

Setup in practice

Zoxide ships as a single binary, but it needs a shell hook to intercept cd and keep its database current. The install step is two lines in your shell config.

For zsh:

eval "$(zoxide init zsh)"

For bash:

eval "$(zoxide init bash)"

For fish, in ~/.config/fish/config.fish:

zoxide init fish | source

Many people also alias cd to z, so every navigation feeds the frecency database:

eval "$(zoxide init zsh --cmd cd)"

After that line, cd is z. For directories zoxide hasn’t seen, it falls back to standard cd. Every directory you visit enters the database.

I run with --cmd cd to keep one navigation command in muscle memory. One command that gets smarter beats two commands that I have to switch between.

What zoxide is not

Zoxide is not a file finder. It only tracks directories. If you want to find a file inside a directory, that’s fzf’s job, or find, or fd.

Zoxide is not a shell history tool. It records navigation only. Ctrl+R (or fzf’s history widget) handles command recall.

Zoxide is not a tool for exploring directories you’ve never visited. It ranks only directories you’ve visited at least once. The first visit still costs you a full cd with a real path, and tab-completion matters for that first trip.

Understanding those boundaries helps. Zoxide is small on purpose. It does one thing (rank directories by frecency) and composes with other tools for everything else.

Common misconceptions

“Zoxide will mess up my muscle memory.” It won’t, if you let it replace cd entirely. Trouble starts when you run z and cd side by side and switch based on whether you “think” zoxide knows the directory. Pick one, use it always, and your hands adapt within a week.

“Zoxide needs to index my whole filesystem.” No. Zoxide records only directories you visit. The database grows as you work, not up front. On a fresh install, zoxide starts empty and stays out of your way until you’ve visited a few places.

“Zoxide is just another cd alias.” The frecency ranking is the whole point. Without the ranking, it would be a worse tab-completer. With the ranking, it predicts where you want to go from a fragment that would be ambiguous to any other tool.

“Zoxide replaces fzf.” It doesn’t. They solve different problems and compose naturally. Fzf filters lists. Zoxide produces a ranked list of directories. Use both.

Trade-offs and limitations

Zoxide is small and focused, but it has costs worth understanding.

• It needs training time. A fresh install is useless. Zoxide improves as you use it, and the real payoff arrives after a week or two of normal work.

• Wrong matches happen. Early on, z config might send you to ~/old-project/config instead of ~/current-project/config because the old one has more history. Run zi once to pick the right directory and bump its score, or use --remove to delete stale entries.

• It’s shell-coupled. Zoxide works through shell hooks. A terminal multiplexer or a non-interactive shell may miss some navigations. This rarely matters in practice, but it’s worth knowing.

• The database can grow. Over the years, stale directories accumulate in your frecency database. Zoxide provides zoxide query -l to list ranked directories and zoxide remove to clean them out. I prune mine maybe once a year.

• It doesn’t work on fresh machines. Moving to a new laptop means starting from zero unless you copy over the database file. For most people that’s fine (rebuilding frecency is fast once you start working), but it’s a real cost.

The core idea

Zoxide solves a problem most people overlook until someone names it: you spend a surprising amount of terminal time retyping paths you already know by heart.

The mental model is a single sentence. Zoxide tracks where you go and lets you jump back with a fragment. The frecency ranking makes “the best match” almost always the one you wanted. The composition with fzf (through zi) handles the cases where it isn’t.

Once the database warms up, z replaces cd for most of my navigation. I still reach for cd when I’m exploring somewhere new, but for the ten directories I live in, one short command and a fragment gets me there.

Next steps

• Install zoxide from the official repository and add the init line to your shell config.
• Try aliasing cd to z with --cmd cd so every navigation trains the frecency database.
• Pair zoxide with fzf if you haven’t already. zi becomes a fuzzy directory picker that knows where you actually work.
• Read about what fzf is to see how the two tools compose.
• Explore shell configuration for more terminal productivity patterns.

References

• zoxide official repository, the source, install instructions, and configuration docs by Ajeet D’Souza.
• z, the original shell-based frecency tool by Rupa Vedula that inspired zoxide.
• autojump, a Python-based predecessor with similar frecency semantics.
• fasd, another shell-based tool that tracks files and directories by frecency.
• What is fzf?, the fuzzy finder that zoxide uses for its interactive zi picker.