📦 ajeetdsouza / zoxide

A smarter cd command. Supports all major shells.

★ 32.7k stars ⑂ 719 forks 👁 32.7k watching ⚖️ MIT License
autojumpbashclicommand-linecommand-line-toolelvishfasdfishfish-shellfzfhacktoberfestjumpnushellpowershellrustshellxonshxontribzzsh
zoxide
📥 Clone https://github.com/ajeetdsouza/zoxide.git
HTTPS git clone https://github.com/ajeetdsouza/zoxide.git
SSH git clone git@github.com:ajeetdsouza/zoxide.git
CLI gh repo clone ajeetdsouza/zoxide
ZIP Desktop VS Code
dependabot[bot] dependabot[bot] Bump actions/upload-artifact from 5 to 6 (#1157) f00fe0f 1 months ago 📝 History
📂 main View all commits →
📁 .cargo
📁 .github
📁 contrib
📁 man
📁 src
📁 templates
📁 tests
📄 .deepsource.toml
📄 .envrc
📄 .gitattributes
📄 .gitignore
📄 build.rs
📄 Cargo.lock
📄 Cargo.toml
📄 CHANGELOG.md
📄 Cross.toml
📄 init.fish
📄 install.sh
📄 justfile
📄 LICENSE
📄 README.md
📄 rustfmt.toml
📄 shell.nix
📄 zoxide.plugin.zsh
📄 README.md

Special thanks to:

Sponsored by Warp
Warp, built for coding with multiple AI agents.
Available for macOS, Linux, and Windows.
Visit warp.dev to learn more.

zoxide

crates.io Downloads Built with Nix

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

Tutorial

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 (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:

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

Linux / WSL

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

> curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh
   >
> > 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 | [guix] | guix install 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 | > | ~Debian~[^1] | ~[Debian Packages]~ | ~apt install zoxide~ | > | Devuan 4.0+ | [Devuan Packages] | apt install zoxide | > | Exherbo Linux | [Exherbo packages] | cave resolve -x repository/rust
cave resolve -x zoxide | > | Fedora 32+ | [Fedora Packages] | dnf install zoxide | > | Gentoo | [Gentoo Packages] | emerge app-shells/zoxide | > | Manjaro | | pacman -S zoxide | > | openSUSE Tumbleweed | [openSUSE Factory] | zypper install zoxide | > | ~Parrot OS~[^1] | | ~apt install zoxide~ | > | ~Raspbian~[^1] | ~[Raspbian Packages]~ | ~apt install zoxide~ | > | Rhino Linux | [Pacstall Packages] | pacstall -I zoxide-deb | > | Slackware 15.0+ | [SlackBuilds] | Instructions | > | Solus | [Solus Packages] | eopkg install zoxide | > | ~Ubuntu~[^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: > > 

> 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)"
   >

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

ApplicationDescriptionPlugin
[aerc]Email clientNatively supported
[alfred]macOS launcher[alfred-zoxide]
[clink]Improved cmd.exe for Windows[clink-zoxide]
[emacs]Text editor[zoxide.el]
[felix]File managerNatively supported
[joshuto]File managerNatively supported
[lf]File managerSee the wiki
[nnn]File manager[nnn-autojump]
[ranger]File manager[ranger-zoxide]
[raycast]macOS launcher[raycast-zoxide]
[rfm]File managerNatively supported
[sesh]tmux session managerNatively supported
[telescope.nvim]Fuzzy finder for Neovim[telescope-zoxide]
[tmux-session-wizard]tmux session managerNatively supported
[tmux-sessionx]tmux session managerNatively supported
[vim] / [neovim]Text editor[zoxide.vim]
[xplr]File manager[zoxide.xplr]
[xxh]Transports shell configuration over SSH[xxh-plugin-prerun-zoxide]
[yazi]File managerNatively supported
[zabb]Finds the shortest possible query for a pathNatively supported
[zesh]zellij session managerNatively supported
[zsh-autocomplete]Realtime completions for zshNatively 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.