zoxide is a blazing fast, intelligent directory jumping tool that makes navigating your filesystem feel like magic.
Here’s how it works in practice. Imagine you’re in your home directory and you want to go to a project folder you’ve been working on, let’s say /Users/yourusername/dev/my-cool-project. Instead of typing the whole path, you can just type:
z cool-project
And zoxide will instantly take you there. What if you have multiple directories with "cool-project" in their name? zoxide learns from your usage. If you’ve visited /Users/yourusername/dev/my-cool-project more recently or more frequently than, say, /Users/yourusername/downloads/cool-project-archive, zoxide will intelligently prioritize the one you’re more likely looking for.
Behind the scenes, zoxide maintains a "frecency" score for every directory you visit. This score is a combination of how frequently you visit a directory and how recently you’ve been there. When you type z something, zoxide searches its database for directories whose paths contain "something". It then ranks these matches by their frecency score and jumps you to the top-ranked one.
The real power comes from its integration. You typically add zoxide to your shell’s startup file (like .zshrc for Zsh). This ensures that every time you cd into a directory, zoxide records that visit and updates the frecency score.
Here’s a typical setup in your .zshrc:
eval "$(zoxide init zsh)"
This single line initializes zoxide for your Zsh session. The init command outputs the necessary shell code to hook into your cd command.
The primary problem zoxide solves is the tedium of repetitive cd commands, especially when dealing with deep or complex directory structures. It eliminates the need for remembering exact paths or relying on cumbersome tab-completion for long directory names. It’s particularly useful for developers who frequently switch between many project directories.
The core configuration for zoxide is minimal, but understanding its behavior is key. The zoxide command itself is the primary interface. For instance, zoxide list will show you all the directories zoxide has indexed, along with their frecency scores.
$ zoxide list
1.000 2023-10-27 10:00:00 /Users/yourusername/dev/my-cool-project
0.750 2023-10-26 15:30:00 /Users/yourusername/docs/important-reports
0.500 2023-10-27 09:00:00 /Users/yourusername/downloads/cool-project-archive
You can also "prune" old entries that zoxide thinks you no longer use with zoxide prune. This keeps the database lean and fast. The frecency algorithm is designed to be dynamic; if you stop visiting a directory, its score will naturally decay over time, and zoxide will eventually stop prioritizing it.
The zoxide database, by default, is stored in ~/.local/share/zoxide/db.proto. This binary file is highly optimized for fast reads and writes. If you ever need to reset zoxide’s memory, you can simply delete this file and re-initialize zoxide in your shell.
A subtle but powerful feature is zoxide’s ability to infer paths even if the directory name you type isn’t an exact match. For example, if you’ve visited /Users/yourusername/projects/backend/api-service and /Users/yourusername/projects/frontend/web-app, typing z api might take you to the backend service, while z web would take you to the frontend. This fuzzy matching is what makes it feel so intelligent.
When zoxide calculates which directory to jump to, it doesn’t just look at the basename of the directory. It considers the entire path for matching, but then ranks based on the frecency of the most specific matching directory. This means if you type z service, and you have /Users/yourusername/projects/backend/api-service and /Users/yourusername/projects/frontend/service-layer, zoxide will weigh which one you’ve visited more and more recently. The ranking algorithm is sophisticated enough to handle these ambiguities gracefully, often surprising users with its accuracy.
The next logical step after mastering zoxide is exploring its integration with other tools, like fzf, for interactive directory selection.