^{Special thanks to:}

Warp, built for coding with multiple AI agents. Available for macOS, Linux, and Windows. Visit warp.dev to learn more.

Processing over 3TB/s of video at peak load, now hiring in SF.

---

zoxide

[![crates.io][crates.io-badge]][crates.io] [![Downloads][downloads-badge]][releases] [![Built with Nix][builtwithnix-badge]][builtwithnix]

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

![Tutorial][tutorial]

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 (bash 4.4+/fish/zsh only)

Read more about the matching algorithm [here][algorithm-matching].

Installation

zoxide can be installed in 4 easy steps:

1. Install binary

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

Linux / WSL

The recommended way to install zoxide is via the install script:

sh 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	[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
Alpine Linux 3.13+	[Alpine Linux Packages]	apk add zoxide
Arch Linux	[Arch Linux Extra]	pacman -S zoxide
~~Debian~~[^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 OS~~[^1] | | ~~apt install zoxide~~ | | ~~Raspbian~~[^1] | ~~[Raspbian Packages]~~ | ~~apt install zoxide~~ | | Rhino Linux | [Pacstall Packages] | pacstall -I zoxide-deb | | Slackware 15.0+ | [SlackBuilds] | [Instructions][slackbuilds-howto] | | Solus | [Solus Packages] | eopkg install zoxide | | ~~Ubuntu~~[^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
[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:

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

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

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

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

sh curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash

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

sh eval "$(zoxide init bash)"

Elvish

Add this to the end of your config file (usually ~/.elvish/rc.elv):

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

sh zoxide init fish | source

Nushell

Add this to the end of your env file (find it by running $nu.env-path in Nushell):

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

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

powershell Invoke-Expression (& { (zoxide init powershell | Out-String) })

Tcsh

Add this to the end of your config file (usually ~/.tcshrc):

sh zoxide init tcsh > ~/.zoxide.tcsh source ~/.zoxide.tcsh

Xonsh

Add this to the end of your config file (usually ~/.xonshrc):

python execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')

Zsh

Add this to the end of your config file (usually ~/.zshrc):

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

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

Note: [Warp] provides its own completions, so Space+Tab completions are not supported there.

1. Install fzf ^(optional)

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

Note: The minimum supported fzf version is v0.51.0.

1. Import your data ^(optional)

If you currently use any of these plugins, you may want to import your data into zoxide. The data file is auto-detected using each plugin's standard conventions.

sh zoxide import <plugin>

Plugin	Command
atuin	zoxide import atuin
autojump	zoxide import autojump
fasd	zoxide import fasd
z	zoxide import z
z.lua	zoxide import z.lua
zsh-z	zoxide import zsh-z

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[^2] 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%