📄 README.md

^{Special thanks to:}

^{Warp, built for coding with multiple AI agents.}

^{Available for macOS, Linux, and Windows.}

^{Visit
warp.dev
to learn more.}

^{Processing over 3TB/s of video at peak load,}

^{now hiring in SF.}

zoxide

zoxide is a smarter cd command, inspired by z and autojump.

It remembers which directories you use most frequently, so you can "jump" to them in just a few keystrokes.
zoxide works on all major shells.

Getting started • Installation • Configuration • Integrations

Getting started

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<SPACE><TAB>  # show interactive completions (bash 4.4+/fish/zsh only)

Read more about the matching algorithm here.

Installation

zoxide can be installed in 4 easy steps:

Install binary

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

Linux / WSL

> The recommended > >

 > > Or, you can use a package manager: > > | Distribution > | ------------------- > |  > | Any > | Any > | Any > | Any > | Any > | Alpine Linux 3.13+ > | Arch Linux > | ~Debian~[^1] > | Devuan 4.0+ > | Exherbo Linux > | Fedora 32+ > | Gentoo > | Manjaro > | openSUSE > | ~Parrot OS~[^1] > | ~Raspbian~[^1] > | Rhino Linux > | Slackware 15.0+ > | Solus > | ~Ubuntu~[^1] > | Void Linux

way to install zoxide is via the install script: class="language-sh">> curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh | Repository                  | Instructions                                                                                          | | --------------------------- | ----------------------------------------------------------------------------------------------------- | Any           | [crates.io]             | cargo install zoxide --locked                                                                       | | [asdf]                      | asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git 
 asdf install zoxide latest | | [conda-forge]               | conda install -c conda-forge zoxide                                                                 | | [guix]                      | guix install zoxide                                                                                 | | [Linuxbrew]                 | brew install zoxide                                                                                 | | [nixpkgs]                   | nix-env -iA nixpkgs.zoxide                                                                          | | [Alpine Linux Packages]     | apk add zoxide                                                                                      | | [Arch Linux Extra]          | pacman -S zoxide                                                                                    | | ~[Debian Packages]~         | ~apt install zoxide~                                                                                    | | [Devuan Packages]           | apt install zoxide                                                                                  | | [Exherbo packages]          | cave resolve -x repository/rust 
 cave resolve -x zoxide                                     | | [Fedora Packages]           | dnf install zoxide                                                                                  | | [Gentoo Packages]           | emerge app-shells/zoxide                                                                            | |                             | pacman -S zoxide                                                                                    | Tumbleweed | [openSUSE Factory]          | zypper install zoxide                                                                               | |                             | ~apt install zoxide~                                                                                | | ~[Raspbian Packages]~       | ~apt install zoxide~                                                                                    | | [Pacstall Packages]         | pacstall -I zoxide-deb                                                                              | | [SlackBuilds]               | Instructions                                                                     | | [Solus Packages]            | eopkg install zoxide                                                                                | | ~[Ubuntu Packages]~         | ~apt install zoxide~                                                                                | | [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:
   >
   > 
> curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh
   >

   

   

   Windows

   > zoxide works with PowerShell, as well as shells running in Cygwin, Git
   > Bash, and MSYS2.
   >
   > The recommended way to install zoxide is via winget:
   >
   > 
> winget install ajeetdsouza.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, you can also use the install script:
   >
   > > curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh
   >

   

   

   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          |
   >
   > Or, run this command in your terminal:
   >
   > 
> curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash
   >

   

   

   Android

   > To install zoxide, use a package manager:
   >
   > | Repository | Instructions         |
   > | ---------- | -------------------- |
   > | [Termux]   | pkg install zoxide |
   >
   > Or, run this command in your terminal:
   >
   > 
> curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash
   >

   

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):
   >
   > 
> eval "$(zoxide init bash)"
   >

   

   

   Elvish

   > Add this to the end of your config file (usually ~/.elvish/rc.elv):
   >
   > 
> 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):
   >
   > 
> zoxide init fish | source
   >

   

   

   Nushell

   > Add this to the end of your env file (find it by running $nu.env-path
   > in Nushell):
   >
   > 
> 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):
   >
   > > source ~/.zoxide.nu
   >
   >
   > Note:
   > zoxide only supports Nushell v0.89.0+.
   

   

   PowerShell

   > Add this to the end of your config file (find it by running
   > echo $profile in PowerShell):
   >
   > 
> Invoke-Expression (& { (zoxide init powershell | Out-String) })
   >

   

   

   Tcsh

   > Add this to the end of your config file (usually ~/.tcshrc):
   >
   > 
> zoxide init tcsh > ~/.zoxide.tcsh
   > source ~/.zoxide.tcsh
   >

   

   

   Xonsh

   > Add this to the end of your config file (usually ~/.xonshrc):
   >
   > 
> execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')
   >

   

   

   Zsh

   > Add this to the end of your config file (usually ~/.zshrc):
   >
   > 
> 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:
   >
   > 
> eval "$(zoxide init posix --hook prompt)"
   >

   

   > Note:
   > [Warp] provides its own completions, so Space+Tab completions are not
   > supported there.
Install fzf ^(optional)

   [fzf] is a command-line fuzzy finder, used by zoxide for completions /
   interactive selection. It can be installed from here.
   > Note:
   > The minimum supported fzf version is v0.51.0.
Import your data ^(optional)

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

   autojump

   > Run this command in your terminal:
   >
   > 
> 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:
   >
   > 
> 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:
   >
   > 
> $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.
--hook <HOOK>
  Changes how often zoxide increments a directory's score:

    | Hook            | Description                       |
    | --------------- | --------------------------------- |
    | none          | Never                             |
    | prompt        | At every shell prompt             |
    | pwd (default) | 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
[alfred] macOS launcher [alfred-zoxide]
[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]
[raycast] macOS launcher [raycast-zoxide]
[rfm] File manager Natively supported
[sesh] tmux session manager Natively supported
[telescope.nvim] Fuzzy finder for Neovim [telescope-zoxide]
[tmux-session-wizard] tmux session manager Natively supported
[tmux-sessionx] 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]
[yazi] File manager Natively supported
[zabb] Finds the shortest possible query for a path Natively supported
[zesh] zellij session manager Natively supported
[zsh-autocomplete] Realtime completions for zsh Natively supported
[^1]:
    Debian / Ubuntu derivatives update their packages very slowly. If you're
    using one of these distributions, consider using the install script instead.
[^2]:
    If you're not sure how to set an environment variable on your shell, check
    out the wiki.

Application	Description	Plugin
[aerc]	Email client	Natively supported
[alfred]	macOS launcher	[alfred-zoxide]
[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]
[raycast]	macOS launcher	[raycast-zoxide]
[rfm]	File manager	Natively supported
[sesh]	`tmux` session manager	Natively supported
[telescope.nvim]	Fuzzy finder for Neovim	[telescope-zoxide]
[tmux-session-wizard]	`tmux` session manager	Natively supported
[tmux-sessionx]	`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]
[yazi]	File manager	Natively supported
[zabb]	Finds the shortest possible query for a path	Natively supported
[zesh]	`zellij` session manager	Natively supported
[zsh-autocomplete]	Realtime completions for zsh	Natively supported