Zoxide: A Smarter CD Command
GitHub - ajeetdsouza/zoxide: A smarter cd command. Supports all major shells.


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


AlmaLinux

dnf install zoxide


Alpine Linux 3.13+
Alpine Linux Packages
apk add zoxide


Arch Linux
Arch Linux Extra
pacman -S zoxide


CentOS Stream

dnf install zoxide


Debian 11+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 OS1

apt install zoxide


Raspbian 11+1
Raspbian Packages
apt install zoxide


RHEL 8+

dnf install zoxide


Rhino Linux
Pacstall Packages
pacstall -I zoxide-deb


Rocky Linux

dnf install zoxide


Slackware 15.0+
SlackBuilds
Instructions


Solus
Solus Packages
eopkg install zoxide


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



Ksh

Add this to the end of your config file (usually ~/.kshrc):
# ksh93
eval "$(zoxide init ksh)"

# mksh, oksh, etc.
eval "$(zoxide init ksh --hook=prompt)"



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

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



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
zoxide only supports fzf v0.33.0 and above.



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


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


yazi
File manager
Natively supported


zabb
Finds the shortest possible query for a path
Natively supported


zsh-autocomplete
Realtime completions for zsh
Natively supported






Debian / Ubuntu derivatives update their packages very slowly. If you're
using one of these distributions, consider using the install script instead. ↩ ↩2 ↩3 ↩4


If you're not sure how to set an environment variable on your shell, check
out the wiki. ↩



