zoxide

A faster way to navigate your filesystem

Introduction

zoxide

cd

z

z.lua

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

| Distribution | Repository | Instructions | | -------------- | ----------------------- | --------------------------------------------------------- | | Any | crates.io |

cargo install zoxide

brew install zoxide

apk add zoxide

yay -Sy zoxide-bin

dnf copr enable atim/zoxide

dnf install zoxide

apt install zoxide

dnf install zoxide

nix-env -iA nixpkgs.zoxide

apt install zoxide

xbps-install -S zoxide

On macOS

| Repository | Instructions | | ----------- | ---------------------- | | crates.io |

cargo install zoxide

brew install zoxide

port install zoxide

On Windows

| Repository | Instructions | | ----------- | ---------------------- | | crates.io |

cargo install zoxide

scoop install zoxide

On BSD

| Distribution | Repository | Instructions | | ------------- | ------------ | ---------------------- | | Any | crates.io |

cargo install zoxide

pkg install zoxide

pkg install zoxide

pkgin install zoxide

On Android

| Repository | Instructions | | ---------- | -------------------- | | Termux |

pkg install zoxide

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

zsh-z

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 

  : 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