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)
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 aftercompinit 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)"
Note:
[Warp] provides its own completions, so Space+Tab completions are not
supported there.
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.
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.
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%
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][glob], 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][fzf-man] 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.
[^1]:
Debian / Ubuntu derivatives update their packages very slowly. If you're
using one of these distributions, consider using the install script instead.
[^2]:
If you're not sure how to set an environment variable on your shell, check
out the [wiki][wiki-env].
What is this?zoxide is a smarter cd command that remembers which directories you use most frequently so you can jump to them with just a few keystrokes.
Is this a standalone app or a shell plugin I add to my config?It is a small Rust binary plus a shell hook: you install the zoxide binary, then add an init line to your shell config, and it defines z and zi commands.
How do I install and set it up?Install the binary via the install script or a package manager (cargo, brew, winget, apt-equivalents, etc.), then add the zoxide init line for your shell (bash, zsh, fish, PowerShell, nushell, elvish, xonsh, tcsh, or any POSIX shell) to your config file.
Do I need fzf or anything else for it to work?The core 'z' jumping works with just the binary and shell hook; fzf is only needed as an optional dependency for interactive selection and completions (minimum v0.51.0).
Can I migrate my existing autojump or fasd history?Yes, zoxide can import data from atuin, autojump, fasd, z, z.lua, and zsh-z using 'zoxide import ', auto-detecting each plugin's data file.
Which shells and platforms does it actually support?It works on bash, zsh, fish, PowerShell, nushell, elvish, xonsh, tcsh and any POSIX shell, with packages available for Linux, macOS, Windows, BSD and Android.
How does zoxide decide which directory to jump to for a given query?It uses a frecency-based matching algorithm that scores directories by frequency and recency of use, picking the best match for the typed query fragments.
Can I change the z and zi command names?Yes, the --cmd flag passed to zoxide init lets you rename the commands, e.g. --cmd j gives you j and ji, or --cmd cd replaces cd entirely.
Does it integrate with other tools like file managers or editors?Yes, zoxide has native or plugin-based integrations with tools like yazi, ranger, nnn, Neovim/vim, tmux session managers, Alfred, Raycast, and more.
How do I keep the database from growing forever?The ZOMAXAGE environment variable controls an aging algorithm that caps the number of entries in the database, defaulting to 10000.
][releases]
zoxide is a smarter cd command that remembers which directories you use most frequently so you can jump to them with just a few keystrokes.