^{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](#getting-started) • [Installation](#installation) • [Configuration](#configuration) • [Integrations](#third-party-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 (bash 4.4+/fish/zsh only)

Read more about the matching algorithm here.

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.

2. Setup zoxide on your shell

To start using zoxide, add it to your shell.

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

3. Install fzf ^(optional)

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

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

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

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/zoxide or $HOME/.local/share/zoxide	/home/alice/.local/share/zoxide
  macOS	$HOME/Library/Application Support/zoxide	/Users/Alice/Library/Application Support/zoxide
  Windows	%LOCALAPPDATA%\zoxide	C:\Users\Alice\AppData\Local\zoxide

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