zoxide

A faster way to navigate your filesystem

Introduction

zoxide is a blazing fast alternative to cd, 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.

Examples

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

Getting started

Step 1: Install zoxide

zoxide works across all major platforms. If your distribution isn't included in the list below, you can directly install the binary from GitHub:

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

If you would rather not run a script, you can download the binary from the Releases page and add it anywhere in your $PATH.

On Linux

On macOS

On Windows

On BSD

On Android

Step 2: Install fzf (optional)

fzf is a command-line fuzzy finder, used by zoxide for interactive selection. Installation instructions can be found here.

Step 3: Add zoxide to your shell

If you currently use z, z.lua, or zsh-z, you may want to first import your existing entries into zoxide:

zoxide import --from z /path/to/db

Alternatively, for autojump:

zoxide import --from autojump /path/to/db

bash

Add the following line to your configuration file (usually ~/.bashrc):

eval "$(zoxide init bash)"

elvish

Add the following line to your configuration file (usually ~/.elvish/rc.elv):

eval $(zoxide init elvish | slurp)

fish

Add the following line to your configuration file (usually ~/.config/fish/config.fish):

zoxide init fish | source

nushell

Initialize zoxide's Nushell script:

zoxide init nushell --hook prompt | save ~/.zoxide.nu

Then, in your Nushell configuration file:

• Prepend __zoxide_hook; to the prompt variable.
• Add the following lines to the startup variable:
  • zoxide init nushell --hook prompt | save ~/.zoxide.nu
  • source ~/.zoxide.nu

powershell

Add the following line to your profile:

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

xonsh

Add the following line to your configuration file (usually ~/.xonshrc):

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

zsh

Add the following line to your configuration file (usually ~/.zshrc):

eval "$(zoxide init zsh)"

Any POSIX shell

Add the following line to your configuration file:

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

Configuration

init flags

• --cmd: changes the prefix of predefined aliases (z, zi).
  • e.g. --cmd j would change the aliases to j and ji respectively.
• --hook <HOOK>: change how often zoxide increments a directory's score:
  • none: never automatically add directories to zoxide.
  • prompt: add the current directory to zoxide at every shell prompt.
  • pwd: whenever the user changes directories, add the new directory to zoxide.
• --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 use them elsewhere.

Environment variables

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 Unix globs, separated by OS-specific characters:

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

• _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.

Third-party integrations

• xxh, via xxh-plugin-prerun-zoxide
• nnn, via autojump plugin