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.
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 variables2 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, 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.
Debian / Ubuntu derivatives update their packages very slowly. If you're
using one of these distributions, consider using the install script instead. ↩︎
If you're not sure how to set an environment variable on your shell, check
out the wiki. ↩︎
