zoxide

A cd command that learns your habits

• Introduction
• Examples
• Getting started
  • Installing zoxide
  • Adding zoxide to your shell
    • zsh
    • bash
    • fish
• Configuration
  • init flags
  • Environment variables

zoxide is a new cd alternative inspired by z and z.lua. It keeps track of the directories you use most frequently, and uses a ranking algorithm to navigate to the best match.

On my system, compiled with the x86_64-unknown-linux-musl target, hyperfine reports that zoxide runs 10-20x faster than z.lua, which, in turn, runs 3x faster than z. This is pretty significant, since this command runs once at every shell prompt, and any slowdown there will result in an increased loading time for every prompt.

z foo       # cd to highest ranked directory matching foo
z foo bar   # cd to highest ranked directory matching foo and bar

z foo/      # can also cd into actual directories

zi foo      # cd with interactive selection using fzf

zq foo      # echo the best match, don't cd

za /foo     # add /foo to the database
zr /foo     # remove /foo from the database

If you have Rust, this should be as simple as:

cargo install zoxide -f

Otherwise, try the install script:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/ajeetdsouza/zoxide/master/install.sh | sh

If you want the interactive fuzzy selection feature, you will also need to install fzf.

If you currently use z, z.lua, or zsh-z, you may want to first migrate your existing database to zoxide:

zoxide migrate /path/to/db

Add the following line to your ~/.zshrc:

eval "$(zoxide init zsh)"

Add the following line to your ~/.bashrc:

eval "$(zoxide init bash)"

Add the following line to your ~/.config/fish/config.fish:

zoxide init fish | source

• --no-define-aliases: don't define extra aliases like zi, zq, za, and zr
• --hook <HOOK>: change the event that adds a new entry to the database (default: prompt)
  • none: never add entries - this will make zoxide useless unless you manually configure a hook
  • prompt: add an entry at every prompt
  • pwd: add an entry whenever you change directories

• $_ZO_ECHO: z will print the matched directory before navigating to it
• $_ZO_DATA: sets the location of the database (default: ~/.zo)
• $_ZO_MAXAGE: sets the maximum total rank after which entries start getting deleted