# How to use zoxide

> Learn how to install and set up zoxide, then jump between frequently used directories with z, interactive selection, and frecency ranking.

Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2026-08-24 | Topics: [CLI](https://flaviocopes.com/tags/cli/) | Canonical: https://flaviocopes.com/zoxide/

[zoxide](https://github.com/ajeetdsouza/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:

```text
/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:

```bash
z flavio
```

zoxide finds the best match and takes me there.

Let's set it up.

## Install zoxide

On macOS, install zoxide with [Homebrew](https://flaviocopes.com/homebrew/):

```bash
brew install zoxide
```

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

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

On Windows, install it with `winget`:

```powershell
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`:

```bash
eval "$(zoxide init zsh)"
```

Then open a new terminal, or reload the file:

```bash
source ~/.zshrc
```

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

```bash
eval "$(zoxide init bash)"
```

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

```fish
zoxide init fish | source
```

For PowerShell, add this to your profile:

```powershell
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`](https://flaviocopes.com/linux-command-cd/) as you already do:

```bash
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:

```bash
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`:

```bash
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:

```bash
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`:

```bash
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:

```bash
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:

```bash
zi app
```

This opens an [fzf](https://github.com/junegunn/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:

```bash
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:

```bash
zoxide query --list --score
```

The output shows each directory and its current score.

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

```bash
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:

```bash
zoxide remove ~/www/old-project
```

You can also open the interactive database editor:

```bash
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:

```bash
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:

```bash
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](https://flaviocopes.com/courses/terminal/).