Getting started

```sh z foo # cd into highest ranked directory matching foo z foo bar # cd into highest ranked directory matching foo and bar z foo / # cd into a subdirectory starting with foo

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)

z foo # show interactive completions (zoxide v0.8.0+, bash 4.4+/fish/zsh only) ```

Read more about the matching algorithm here.

Installation

zoxide can be installed in 4 easy steps:

1. Install binary

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

   Linux

   The recommended way to install zoxide is via the install script:

   sh curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash

   Or, you can use a package manager:

   | Distribution | Repository | Instructions | | ------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- | | Any | [crates.io] | cargo install zoxide --locked | | Any | [asdf] | asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git
asdf install zoxide latest | | Any | [conda-forge] | conda install -c conda-forge zoxide | | Any | [Linuxbrew] | brew install zoxide | | Any | [nixpkgs] | nix-env -iA nixpkgs.zoxide | | Alpine Linux 3.13+ | [Alpine Linux Packages] | apk add zoxide | | Arch Linux | [Arch Linux Extra] | pacman -S zoxide | | CentOS 7+ | [Copr] | dnf copr enable atim/zoxide
dnf install zoxide | | Debian 11+[^1] | [Debian Packages] | apt install zoxide | | Devuan 4.0+[^1] | [Devuan Packages] | apt install zoxide | | Fedora 32+ | [Fedora Packages] | dnf install zoxide | | Gentoo | [GURU Overlay] | eselect repository enable guru
emerge --sync guru
emerge app-shells/zoxide | | Manjaro | | pacman -S zoxide | | openSUSE Tumbleweed | [openSUSE Factory] | zypper install zoxide | | Parrot OS[^1] | | apt install zoxide | | Raspbian 11+[^1] | [Raspbian Packages] | apt install zoxide | | Slackware 15.0+ | [SlackBuilds] | Instructions | | Ubuntu 21.04+[^1] | [Ubuntu Packages] | apt install zoxide | | Void Linux | [Void Linux Packages] | xbps-install -S zoxide |

   macOS

   To install zoxide, use a package manager:

   | Repository | Instructions | | --------------- | ----------------------------------------------------------------------------------------------------- | | [crates.io] | cargo install zoxide --locked | | [Homebrew] | brew install zoxide | | [asdf] | asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git
asdf install zoxide latest | | [conda-forge] | conda install -c conda-forge zoxide | | [MacPorts] | port install zoxide | | [nixpkgs] | nix-env -iA nixpkgs.zoxide |

   Or, run this command in your terminal:

   sh curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash

   Windows

   The recommended way to install zoxide is via winget:

   sh winget install zoxide

   Or, you can use an alternative package manager:

   | Repository | Instructions | | --------------- | ------------------------------------- | | [crates.io] | cargo install zoxide --locked | | [Chocolatey] | choco install zoxide | | [conda-forge] | conda install -c conda-forge zoxide | | [Scoop] | scoop install zoxide |

   If you're using Cygwin, Git Bash, or MSYS2, use the install script instead:

   sh curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash

   BSD

   To install zoxide, use a package manager:

   | Distribution | Repository | Instructions | | ------------- | --------------- | ------------------------------- | | Any | [crates.io] | cargo install zoxide --locked | | DragonFly BSD | [DPorts] | pkg install zoxide | | FreeBSD | [FreshPorts] | pkg install zoxide | | NetBSD | [pkgsrc] | pkgin install zoxide |

   Android

   To install zoxide, use a package manager:

   | Repository | Instructions | | ---------- | -------------------- | | [Termux] | pkg install zoxide |

2. Setup zoxide on your shell

   To start using zoxide, add it to your shell.

   Bash

   Add this to the end of your config file (usually ~/.bashrc):

   sh eval "$(zoxide init bash)"

   Elvish

   Add this to the end of your config file (usually ~/.elvish/rc.elv):

   sh eval (zoxide init elvish | slurp)

   Note zoxide only supports elvish v0.18.0 and above.

   Fish

   Add this to the end of your config file (usually ~/.config/fish/config.fish):

   fish zoxide init fish | source

   Nushell

   Add this to the end of your env file (find it by running $nu.env-path in Nushell):

   sh zoxide init nushell | save -f ~/.zoxide.nu

   Now, add this to the end of your config file (find it by running $nu.config-path in Nushell):

   sh source ~/.zoxide.nu

   Note zoxide only supports Nushell v0.73.0 and above.

   PowerShell

   Add this to the end of your config file (find it by running echo $profile in PowerShell):

   powershell Invoke-Expression (& { (zoxide init powershell | Out-String) })

   Xonsh

   Add this to the end of your config file (usually ~/.xonshrc):

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

   Zsh

   Add this to the end of your config file (usually ~/.zshrc):

   sh eval "$(zoxide init zsh)"

   For completions to work, the above line must be added after compinit is called. You may have to rebuild your completions cache by running rm ~/.zcompdump*; compinit.

   Any POSIX shell

   Add this to the end of your config file:

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

3. Install fzf <sup>(optional)</sup>

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

   Note zoxide only supports fzf v0.33.0 and above.

4. Import your data <sup>(optional)</sup>

   If you currently use any of these plugins, you may want to import your data into zoxide:

   autojump

   Run this command in your terminal:

   sh zoxide import --from=autojump "/path/to/autojump/db"

   The path usually varies according to your system:

   | OS | Path | Example | | ------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------ | | Linux | $XDG_DATA_HOME/autojump/autojump.txt or $HOME/.local/share/autojump/autojump.txt | /home/alice/.local/share/autojump/autojump.txt | | macOS | $HOME/Library/autojump/autojump.txt | /Users/Alice/Library/autojump/autojump.txt | | Windows | %APPDATA%\autojump\autojump.txt | C:\Users\Alice\AppData\Roaming\autojump\autojump.txt |

   fasd, z, z.lua, zsh-z

   Run this command in your terminal:

   sh zoxide import --from=z "path/to/z/db"

   The path usually varies according to your system:

   | Plugin | Path | | ---------------- | ----------------------------------------------------------------------------------- | | fasd | $_FASD_DATA or $HOME/.fasd | | z (bash/zsh) | $_Z_DATA or $HOME/.z | | z (fish) | $Z_DATA or $XDG_DATA_HOME/z/data or $HOME/.local/share/z/data | | z.lua (bash/zsh) | $_ZL_DATA or $HOME/.zlua | | z.lua (fish) | $XDG_DATA_HOME/zlua/zlua.txt or $HOME/.local/share/zlua/zlua.txt or $_ZL_DATA | | zsh-z | $ZSHZ_DATA or $_Z_DATA or $HOME/.z |

   ZLocation

   Run this command in PowerShell:

   powershell $db = New-TemporaryFile (Get-ZLocation).GetEnumerator() | ForEach-Object { Write-Output ($_.Name+'|'+$_.Value+'|0') } | Out-File $db zoxide import --from=z $db

Configuration

Flags

When calling zoxide init, the following flags are available:

• --cmd
  • Changes the prefix of the z and zi commands.
  • --cmd j would change the commands to (j, ji).
  • --cmd cd would replace the cd command (doesn't work on Nushell / POSIX shells).
• --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-cmd
  • Prevents zoxide from defining the z and zi commands.
  • These functions will still be available in your shell as __zoxide_z and __zoxide_zi, should you choose to redefine them.

Environment variables

Environment variables[^2] can be used for configuration. They must be set before zoxide init is called.

• _ZO_DATA_DIR
  • Specifies the directory in which the database is stored.
  • 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 | %LOCALAPPDATA% | C:\Users\Alice\AppData\Local |
• _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] during interactive selection. 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

| Application | Description | Plugin | | --------------------- | -------------------------------------------- | -------------------------- | | [aerc] | Email client | Natively supported | | [clink] | Improved cmd.exe for Windows | [clink-zoxide] | | [emacs] | Text editor | [zoxide.el] | | [felix] | File manager | Natively supported | | [joshuto] | File manager | Natively supported | | [lf] | File manager | See the wiki | | [nnn] | File manager | [nnn-autojump] | | [ranger] | File manager | [ranger-zoxide] | | [telescope.nvim] | Fuzzy finder for Neovim | [telescope-zoxide] | | [t] | tmux session manager | Natively supported | | [tmux-session-wizard] | tmux session manager | Natively supported | | [vim] / [neovim] | Text editor | [zoxide.vim] | | [xplr] | File manager | [zoxide.xplr] | | [xxh] | Transports shell configuration over SSH | [xxh-plugin-prerun-zoxide] | | [zabb] | Finds the shortest possible query for a path | Natively supported | | [zsh-autocomplete] | Realtime completions for zsh | Natively supported |

using one of these distributions, consider using the install script instead.

out the [wiki][wiki-env].