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 (zoxide v0.8.0+, bash 4.4+/fish/zsh only)

Read more about the matching algorithm here.

Installation

Step 1: Install zoxide

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

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

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

curl.exe -A "MS" https://webinstall.dev/zoxide | powershell

Step 2: Add zoxide to your shell

To start using zoxide, add it to your shell.

eval "$(zoxide init bash)"

eval (zoxide init elvish | slurp)

zoxide init fish | source

zoxide init nushell --hook prompt | save ~/.zoxide.nu

source ~/.zoxide.nu

# For zoxide v0.8.0+
Invoke-Expression (& {
    $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
    (zoxide init --hook $hook powershell | Out-String)
})

# For older versions of zoxide
Invoke-Expression (& {
    $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
    (zoxide init --hook $hook powershell) -join "`n"
})

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

eval "$(zoxide init zsh)"

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.

Note: zoxide only supports fzf v0.21.0 and above.

Step 4: Import your data (optional)

If you currently use any of the following utilities, you may want to import your data into zoxide:

zoxide import --from autojump path/to/db

zoxide import --from z path/to/db

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 (doesn't work on Nushell / POSIX shells).
• --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-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 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.

Third-party integrations