^{Special thanks to:}

^{Warp, the intelligent terminal}

^{Available for MacOS, Linux, and Windows}

^{Visit
warp.dev
to learn more.}

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 (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+~~¹ ~~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~~¹ ~~apt install zoxide~~

~~Raspbian 11+~~¹ ~~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+~~¹ ~~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) })
```
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 variables² 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. ↩ ↩² ↩³ ↩⁴
If you're not sure how to set an environment variable on your shell, check out the wiki. ↩

License

SamirTalwar/zoxide

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages