Skip to content
Get packs

Guide · Open source

How to use zoxide: jump to folders with a few letters

Updated · written with AI from the project's own documentation and checked against our catalogue data

zoxide is a replacement for the cd command that remembers the directories you use most often. You type a few letters of a folder name and it jumps there, instead of typing the full path. This guide covers what it does, how to install it, the main z and zi commands, and when it is a good fit.

zoxideajeetdsouza/zoxide · ★ 40.4k · MIT

Quick start

  1. 1Install zoxide. Use the package manager for your platform, such as winget on Windows or brew on macOS and Linux. The README also lists cargo install zoxide --locked for any platform with Rust.
  2. 2Add zoxide to your shell. Follow the Configuration section of the README for your shell. zoxide supports bash, zsh, fish, PowerShell and xonsh.
  3. 3Restart your terminal. Open a new shell session so the setup takes effect.
  4. 4Visit folders as you normally do. Use cd or move between projects for a while so zoxide can record which directories you use.
  5. 5Jump with z. Type z followed by a few letters of a folder name to move there.
  6. 6Choose with zi. Use zi foo when several directories match and you want to pick one. This needs fzf.

What zoxide does

zoxide is a smarter cd command, inspired by z and autojump. It remembers which directories you use most frequently, so you can jump to them in just a few keystrokes.

According to the project, zoxide works on all major shells.

Install zoxide on macOS, Linux, Windows or BSD

The README lists package-manager options for each platform. The recommended route on Windows is winget. On Linux and macOS, many distributions and Homebrew provide it. Cargo works on any platform with Rust, and the install script is available for Linux, WSL, macOS and BSD.

  • Cargo (any platform with Rust): cargo install zoxide --locked
  • Homebrew (macOS/Linux): brew install zoxide
  • Windows (recommended): winget install ajeetdsouza.zoxide
  • Install script (Linux/WSL/macOS): curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh
brew install zoxide

Jump to directories with z

Type z followed by part of a folder name. zoxide moves you to the highest ranked directory that matches. You can give several words to narrow the match, or use a path with a trailing slash.

z also still works like a regular cd for full paths and for going up one level.

  • z foo: cd into the highest ranked directory matching foo
  • z foo bar: match directories that contain both foo and bar
  • z foo /: cd into a subdirectory starting with foo
  • z ~/foo: works like a regular cd
  • z ..: go one level up
  • z -: go to the previous directory
z foo z foo bar z foo / z ~/foo z .. z -

Pick a folder interactively with zi

If several directories match, zi lets you choose from a list. The README says this uses fzf, so fzf needs to be available for this command.

Tab completion for matches is available in bash 4.4+, fish and zsh, according to the README.

  • zi foo: interactive selection using fzf
  • foo then SPACE then TAB: show interactive completions (bash 4.4+, fish, zsh only)
zi foo z foo<SPACE><TAB>

Understand how zoxide ranks directories

zoxide ranks directories by how often and how recently you visit them, not by the path you typed. Its history builds up as you move around, so results get better with use. The README links to a page describing the matching algorithm.

  • Directories you visit often and recently rank higher.
  • A new install has little history, so early jumps may not land where you expect.

What people use it for

  • Switching between many project folders in a terminal without typing full paths.
  • Returning to a deep directory like a build output folder with a short partial name.
  • Using the same jump command across bash, zsh, fish or PowerShell.
  • Picking among several matching folders with the fzf-based zi command.

Frequently asked questions

Is zoxide free?

zoxide is open source under the MIT licence, according to its repository. You can use, copy and modify it under those terms.

What are the requirements for zoxide?

The source does not list specific prerequisites. You need a supported shell, and zi requires fzf. Installing with cargo requires Rust.

Which shells does zoxide support?

The README says zoxide works on all major shells. The project lists bash, zsh, fish, PowerShell and xonsh as supported shells.

How is zoxide different from the cd command?

zoxide ranks directories by frequency and recency rather than by the typed path. That means it may not behave exactly like cd in every edge case.

What are alternatives to zoxide?

The README names z, autojump, fasd and jump as comparable projects. zoxide is inspired by z and autojump.

Why does zoxide jump to the wrong folder?

zoxide relies on the history it has built. A new install has little history, and a folder you rarely visit ranks lower. Use zi to pick from the matches, or visit the right folder more often.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

zoxide suits developers who move between many project folders in a terminal and want shorter jumps across shells. It is less useful if you rarely use the terminal, or if you need cd to behave exactly like the built-in command in every case.

Install options & downloads