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/fish/zsh only)

Read more about the matching algorithm here.

Installation

Step 1: Install zoxide

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

Linux

To install zoxide, run this command in your terminal:

curl -sS https://webinstall.dev/zoxide | bash

Alternatively, you can use a package manager:

Distribution	Repository	Instructions
Any	crates.io	`cargo install zoxide --locked`
Any	conda-forge	`conda install -c conda-forge zoxide`
Any	Linuxbrew	`brew install zoxide`
Alpine Linux 3.13+	Alpine Linux Packages	`apk add zoxide`
Arch Linux	Arch Linux Community	`pacman -S zoxide`
CentOS 7+	Copr	`dnf copr enable atim/zoxide` `dnf install zoxide`
Debian 11+	Debian Packages	`apt install zoxide`
Devuan 4.0+	Devuan Packages	`apt install zoxide`
Fedora 32+	Fedora Packages	`dnf install zoxide`
Gentoo	GURU Overlay	`eselect repository enable guru` `emerge --sync guru` `emerge app-shells/zoxide`
Manjaro		`pacman -S zoxide`
NixOS	nixpkgs	`nix-env -iA nixpkgs.zoxide`
Parrot OS		`apt install zoxide`
Raspbian 11+	Raspbian Packages	`apt 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`
conda-forge	`conda install -c conda-forge zoxide`
Homebrew	`brew install zoxide`
MacPorts	`port install zoxide`

Windows

To install zoxide, run this command in your command prompt:

curl.exe -A "MS" https://webinstall.dev/zoxide | powershell

Alternatively, you can use a 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`

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`

Android

To install zoxide, use a package manager:

Repository	Instructions
Termux	`pkg install zoxide`

Step 2: Add zoxide to your shell

To start using zoxide, add it to your shell.

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)

Note: zoxide only supports elvish v0.16.0 and above.

Fish

Add this to your configuration (usually ~/.config/fish/config.fish):

zoxide init fish | source

Nushell

Add this to your configuration (find it by running config path in Nushell):

startup = ["zoxide init nushell --hook prompt | save ~/.zoxide.nu", "source ~/.zoxide.nu"]

Note: zoxide only supports Nushell v0.37.0 and above.

PowerShell

Add this to your configuration (find it by running echo $profile in PowerShell):

# For zoxide v0.8.0+
Invoke-Expression (& {
    $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
    (zoxide init --hook $hook powershell | Out-String)
})

# For older versions of zoxide
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)"

For completions to work, the above line must be added after compinit is called. You may have to rebuild your cache by running rm ~/.zcompdump*; compinit.

Any POSIX shell

Add this to your configuration:

eval "$(zoxide init posix --hook prompt)"

Step 3: Install fzf (optional)

fzf is a command-line fuzzy finder, used by zoxide for interactive selection. It can be installed from here. zoxide supports fzf v0.21.0+.

Step 4: Import your data (optional)

If you currently use any of the following utilities, you may want to import your data into zoxide:

autojump

zoxide import --from autojump path/to/db

z, z.lua, or zsh-z

zoxide import --from z path/to/db

Configuration

Flags

When calling zoxide init, the following flags are available:

--cmd
- Changes the prefix of predefined aliases (z, zi).
- --cmd j would change the aliases to (j, ji).
- --cmd cd would replace the cd command (doesn't work on Nushell / POSIX shells).
--hook <HOOK>
- Changes how often zoxide increments a directory's score:
  
  Hook Description
  
  none Never
  
  prompt At every shell prompt
  
  pwd Whenever the directory is changed
--no-aliases
- Don't define aliases (z, zi).
- These functions will still be available in your shell as __zoxide_z and __zoxide_zi, should you choose to redefine them.

Hook	Description
`none`	Never
`prompt`	At every shell prompt
`pwd`	Whenever the directory is changed

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	`{FOLDERID_RoamingAppData}`	`C:\Users\Alice\AppData\Roaming`

_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.

OS	Separator	Example
Linux / macOS / BSD	`:`	`$HOME:$HOME/private/*`
Windows	`;`	`$HOME;$HOME/private/*`

Third-party integrations

Application	Description	Plugin
emacs	Text editor	zoxide.el
nnn	File manager	nnn-autojump
ranger	File manager	ranger-zoxide
telescope.nvim	Fuzzy finder for Neovim	telescope-zoxide
vim	Text editor	zoxide.vim
xplr	File manager	zoxide.xplr
xxh	Transports shell configuration over SSH	xxh-plugin-prerun-zoxide
zsh-autocomplete	Realtime completions for zsh	Supported by default

julienvincendeau-rc/zoxide

zoxide

Getting started

Installation

Step 1: Install zoxide

Step 2: Add zoxide to your shell

Step 3: Install fzf (optional)

Step 4: Import your data (optional)

Configuration

Flags

Environment variables

Third-party integrations