zoxide

A smarter cd command for your terminal

zoxide is a blazing fast replacement for your cd command, 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.

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

z ~/foo      # z also works like a regular cd command
z foo/       # cd into relative path
z ..         # cd one level up
z -          # cd into previous directory

zi foo       # cd with interactive selection (using fzf)

Read more about the matching algorithm here.

zoxide runs on most major platforms. If your platform isn't listed below, please open an issue.

To start using zoxide, add it to your shell.

eval "$(zoxide init bash)"

eval (zoxide init elvish | slurp)

zoxide init fish | source

prompt = "__zoxide_hook;__zoxide_prompt"
startup = ["zoxide init nushell --hook prompt | save ~/.zoxide.nu", "source ~/.zoxide.nu"]

Invoke-Expression (& {
    $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
    (zoxide init --hook $hook powershell) -join "`n"
})

execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')

eval "$(zoxide init zsh)"

eval "$(zoxide init posix --hook prompt)"

fzf is a command-line fuzzy finder, used by zoxide for interactive selection. It can be installed from here.

If you currently use any of the following utilities, you may want to import your data into zoxide:

zoxide import --from autojump path/to/db

zoxide import --from z path/to/db

When calling zoxide init, the following flags are available:

• --cmd
  • Changes the prefix of predefined aliases (z, zi).
  • e.g. --cmd j would change the aliases to j and ji respectively.
• --hook <HOOK>
  • Changes how often zoxide increments a directory's score:

    Hook	Description
    none	Never
    prompt	At every shell prompt
    pwd	Whenever the directory is changed

• --no-aliases
  • Don't define extra aliases (z, zi).
  • These functions will still be available in your shell as __zoxide_z and __zoxide_zi, should you choose to redefine them.

Be sure to set these before calling zoxide init.

• _ZO_DATA_DIR
  • Specifies the directory in which zoxide should store its database.
  • The default value varies across OSes:

    OS	Path	Example
    Linux / BSD	$XDG_DATA_HOME or $HOME/.local/share	/home/alice/.local/share
    macOS	$HOME/Library/Application Support	/Users/Alice/Library/Application Support
    Windows	{FOLDERID_RoamingAppData}	C:\Users\Alice\AppData\Roaming

• _ZO_ECHO
  • When set to 1, z will print the matched directory before navigating to it.
• _ZO_EXCLUDE_DIRS
  • Excludes the specified directories from the database.
  • This is provided as a list of globs, separated by OS-specific characters:

    OS	Separator	Example
    Linux / macOS / BSD	:	$HOME:$HOME/private/*
    Windows	;	$HOME;$HOME/private/*

  • By default, this is set to "$HOME".
• _ZO_FZF_OPTS
  • Custom options to pass to fzf. See man fzf for the list of options.
• _ZO_MAXAGE
  • Configures the aging algorithm, which limits the maximum number of entries in the database.
  • By default, this is set to 10000.
• _ZO_RESOLVE_SYMLINKS
  • When set to 1, z will resolve symlinks before adding directories to the database.

• emacs. You can use zoxide for navigation with the zoxide.el plugin.
• nnn is a terminal file manager. You can use zoxide for navigation with the official autojump plugin.
• ranger is a terminal file manager. You can use zoxide for navigation with the ranger-zoxide plugin.
• telescope.nvim is a fuzzy finder for neovim. You can use it with zoxide via the telescope-zoxide plugin.
• vim / neovim. You can use zoxide for navigation with the zoxide.vim plugin.
• xxh transports your shell configuration over SSH. You can use zoxide over SSH via the xxh-plugin-prerun-zoxide plugin.
• zsh-autocomplete adds realtime completions to zsh. It supports zoxide out of the box.