How to use zoxide

zoxide is a smarter cd command.

It remembers the directories you use most often. You can then jump to one by typing a small part of its path.

Suppose I often work in this directory:

/Users/flavio/www/flaviocopes.com

With cd, I have to type the path or move through it one directory at a time.

With zoxide, I can type:

z flavio

zoxide finds the best match and takes me there.

Let’s set it up.

Install zoxide

On macOS, install zoxide with Homebrew:

brew install zoxide

On Linux and WSL, the project recommends its install script:

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

On Windows, install it with winget:

winget install ajeetdsouza.zoxide

Installing the program is only the first step. You must also connect it to your shell.

Set up your shell

I use Zsh, which is the default shell on current macOS versions.

Add this line to the end of ~/.zshrc:

eval "$(zoxide init zsh)"

Then open a new terminal, or reload the file:

source ~/.zshrc

If you use Bash, add this to ~/.bashrc instead:

eval "$(zoxide init bash)"

Fish uses a different syntax in ~/.config/fish/config.fish:

zoxide init fish | source

For PowerShell, add this to your profile:

Invoke-Expression (& { (zoxide init powershell | Out-String) })

The initialization code creates the z and zi commands. It also teaches zoxide about the directories you visit.

Let zoxide learn your directories

Use the terminal normally after installing zoxide.

Move into your projects with cd as you already do:

cd ~/www/flaviocopes.com
cd ~/www/prototyped.dev
cd ~/www/thevalleyofcode.com

zoxide records those visits in its local database. Directories you use frequently get a higher rank.

You can also add a directory manually:

zoxide add ~/www/flaviocopes.com

You rarely need this. Visiting a directory is enough.

Jump with the z command

Once zoxide knows a directory, pass part of its name to z:

z flaviocopes

You do not need to start from the same parent directory. The match comes from zoxide’s database, not your current location.

You can pass multiple words when one is not enough:

z www myapp

Every term must appear in the path, in the same order. Matching is case-insensitive.

The last term normally matches the final directory name. For example, this can match ~/www/myapp:

z myapp

But it will not pick ~/www/myapp/archive because myapp is not the final directory in that path.

The z command also works like cd for normal paths:

z ..
z -
z ~/Downloads
z projects/

z .. moves to the parent directory. z - returns to the previous directory.

Choose a directory interactively with zi

Sometimes several directories match the same query.

Use zi to choose one interactively:

zi app

This opens an fzf list containing the matches. Start typing to filter it, move with the arrow keys, then press Enter.

Install fzf first if you do not already have it:

brew install fzf

On Linux, use your distribution’s package manager or follow the fzf installation instructions.

See what zoxide has learned

You can inspect the database with:

zoxide query --list --score

The output shows each directory and its current score.

To see only matches for a query, add a keyword:

zoxide query --list --score app

This is useful when z app goes somewhere you did not expect.

To remove a directory from the database, run:

zoxide remove ~/www/old-project

You can also open the interactive database editor:

zoxide edit

How zoxide decides where to go

zoxide uses frecency: a combination of frequency and recency.

Every directory starts with a score. Visiting it again increases that score. Recent visits count more than old ones when zoxide chooses between matches.

This makes the ranking adapt to your habits. A project you work on every day will beat an old directory with a similar name.

If zoxide picks the wrong directory, use more search terms or choose with zi. The ranking improves as you keep using it.

Replace cd with zoxide

zoxide can replace the cd command entirely.

For Zsh, initialize it like this:

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

Now cd gets zoxide’s matching behavior while still accepting regular paths.

I prefer keeping z and cd separate at first. The distinction is useful: cd means an exact path, while z means “find the directory I probably want.”

Once that feels natural, replacing cd is an option.

Exclude directories

You may have directories you never want zoxide to remember.

Set _ZO_EXCLUDE_DIRS before the zoxide init line in your shell configuration:

export _ZO_EXCLUDE_DIRS="$HOME/private/*:$HOME/tmp/*"
eval "$(zoxide init zsh)"

On macOS, Linux, and BSD, separate patterns with :. Windows uses ;.

This is useful for temporary build directories, mounted volumes, and folders whose names you do not want in the database.

Where zoxide fits

I would use zoxide for interactive terminal work, especially when moving between many projects every day.

I would not use it inside shell scripts. A script should use an explicit path because its behavior must not depend on one person’s directory history.

zoxide also needs a little time to learn. On a fresh installation, visit your main directories once or add them manually.

After that, z becomes one of those small commands that removes friction every time you open the terminal.

If you want to get more comfortable with paths, commands, and shell navigation first, start with my free Terminal Course.