zoxide
A smarter cd command for your terminal
zoxide is a blazing fast replacement for your cd command, inspired by z and z.lua. It keeps track of the directories you use most frequently, and uses a ranking algorithm to navigate to the best match.
Examples
z foo # cd into highest ranked directory matching foo
z foo bar # cd into highest ranked directory matching foo and bar
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)
Read more about the matching algorithm here.
Getting started
Step 1: Install zoxide
zoxide works across all major platforms. If your distribution isn't included in the list below, you can download the binary from the Releases page and copy it to your $PATH.
On Linux
| Distribution | Repository | Instructions |
|---|---|---|
| Any | crates.io | cargo install zoxide |
| Any | Linuxbrew | brew install zoxide |
| Alpine Linux 3.13+ | Alpine Linux Packages | apk add zoxide |
| Arch Linux | AUR | yay -Sy zoxide-bin |
| CentOS 7+ | Copr | dnf copr enable atim/zoxide dnf install zoxide |
| Debian Testing | Debian Packages | apt install zoxide |
| Devuan 4.0+ | Devuan Packages | apt install zoxide |
| Fedora 32+ | Fedora Packages | dnf install zoxide |
| Gentoo | dm9pZCAq Overlay | eselect repository enable dm9pZCAq emerge --sync dm9pZCAq emerge app-shells/zoxide |
| NixOS | nixpkgs | nix-env -iA nixpkgs.zoxide |
| Parrot OS | apt install zoxide |
|
| Ubuntu 21.04+ | Ubuntu Packages | apt install zoxide |
| Void Linux | Void Linux Packages | xbps-install -S zoxide |
On macOS
| Repository | Instructions |
|---|---|
| crates.io | cargo install zoxide |
| Homebrew | brew install zoxide |
| MacPorts | port install zoxide |
On Windows
| Repository | Instructions |
|---|---|
| crates.io | cargo install zoxide |
| Scoop | scoop install zoxide |
On BSD
| Distribution | Repository | Instructions |
|---|---|---|
| Any | crates.io | cargo install zoxide |
| DragonFly BSD | DPorts | pkg install zoxide |
| FreeBSD | FreshPorts | pkg install zoxide |
| NetBSD | pkgsrc | 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, or zsh-z, you may want to first import your existing entries into zoxide:
zoxide import --from z path/to/db
Alternatively, for autojump (note that scores are not imported):
zoxide import --from autojump path/to/db
bash
Add this to your configuration (usually ~/.bashrc):
eval "$(zoxide init bash)"
elvish
Add this to your configuration (usually ~/.elvish/rc.elv):
eval (zoxide init elvish | slurp)
fish
Add this to your configuration (usually ~/.config/fish/config.fish):
zoxide init fish | source
nushell
Initialize zoxide's Nushell script:
zoxide init nushell --hook prompt | save ~/.zoxide.nu
Add this to your configuration (usually ~/.config/nu/config.toml):
prompt = "__zoxide_hook;__zoxide_prompt"
startup = ["zoxide init nushell --hook prompt | save ~/.zoxide.nu", "source ~/.zoxide.nu"]
You can replace __zoxide_prompt with a custom prompt.
powershell
Add this to your configuration (the location is stored in $profile):
Invoke-Expression (& {
$hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
(zoxide init --hook $hook powershell) -join "`n"
})
xonsh
Add this to your configuration (usually ~/.xonshrc):
execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')
zsh
Add this to your configuration (usually ~/.zshrc):
eval "$(zoxide init zsh)"
Any POSIX shell
Add this to your configuration:
eval "$(zoxide init posix --hook prompt)"
Configuration
init flags
--cmd: changes the prefix of predefined aliases (z,zi).- e.g.
--cmd jwould change the aliases tojandjirespectively.
- e.g.
--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_zand__zoxide_zi, should you choose to use them elsewhere.
- These functions will still be available in your shell as
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_HOMEor$HOME/.local/share/home/alice/.local/sharemacOS $HOME/Library/Application Support/Users/Alice/Library/Application SupportWindows {FOLDERID_RoamingAppData}C:\Users\Alice\AppData\Roaming
_ZO_ECHO- When set to
1,zwill print the matched directory before navigating to it.
- When set to
_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. Seeman fzffor the list of options.
- Custom options to pass to
_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,zwill resolve symlinks before adding directories to the database.
- When set to
![[FR] Add `zoxide query --list-fast`](https://avatars.githubusercontent.com/u/36224762?v=4)
12 Nov 5, 2022
310 Jan 5, 2023
1.4k Dec 29, 2022
26 Dec 2, 2022
31.6k Dec 30, 2022
165 Dec 4, 2022
344 Dec 31, 2022
17 Dec 18, 2022
26 Dec 5, 2022
8 Mar 2, 2023
6 Feb 23, 2023
78 Apr 10, 2023
97 Apr 14, 2023
3 Apr 3, 2023
7 Jul 7, 2023
189 Aug 1, 2023
5 Sep 1, 2023
3 Nov 17, 2023
20.3k Jan 8, 2023