zoxide/README.md

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 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
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		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
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
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
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.36.0 and above.

powershell

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

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

Step 3: Install fzf (optional)

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

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).
  • e.g. --cmd j would change the aliases to j and ji respectively.
• --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 extra aliases (z, zi).
  • These functions will still be available in your shell as __zoxide_z and __zoxide_zi, should you choose to redefine them.

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

• emacs. You can use zoxide for navigation with the zoxide.el plugin.
• nnn is a terminal file manager. You can use zoxide for navigation with the official autojump plugin.
• ranger is a terminal file manager. You can use zoxide for navigation with the ranger-zoxide plugin.
• telescope.nvim is a fuzzy finder for neovim. You can use it with zoxide via the telescope-zoxide plugin.
• vim / neovim. You can use zoxide for navigation with the zoxide.vim plugin.
• xxh transports your shell configuration over SSH. You can use zoxide over SSH via the xxh-plugin-prerun-zoxide plugin.
• zsh-autocomplete adds realtime completions to zsh. It supports zoxide out of the box.