zoxide

A smarter cd command for your terminal

zoxide is a blazing fast replacement for your cd command, inspired by
z and z.lua. It keeps track of the directories you use most
frequently, and uses a ranking algorithm to navigate to the best match.

Examples

z foo        # cd into highest ranked directory matching foo
z foo bar    # cd into highest ranked directory matching foo and bar

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)

Read more about the matching algorithm here.

Getting started

Step 1: Install zoxide

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

curl -sS https://webinstall.dev/zoxide | 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

startup = ["zoxide init nushell --hook prompt | save ~/.zoxide.nu", "source ~/.zoxide.nu"]

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.

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 predefined aliases (z, zi).
• e.g. --cmd j would change the aliases to j and ji respectively.
• --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-aliases
• Don't define extra aliases (z, zi).
• These functions will still be available in your shell as __zoxide_z and
  __zoxide_zi, should you choose to redefine them.

Environment variables

Be sure to set these before calling zoxide init.

• _ZO_DATA_DIR
• Specifies the directory in which zoxide should store its database.
• 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 | {FOLDERID_RoamingAppData} | C:\Users\Alice\AppData\Roaming |
• _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. 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

• emacs. You can use zoxide for navigation with the
  zoxide.el (gitlab.com) plugin.
• nnn is a terminal file manager. You can use zoxide for navigation
  with the official autojump plugin.
• ranger is a terminal file manager. You can use zoxide for
  navigation with the ranger-zoxide plugin.
• telescope.nvim (github.com) is a fuzzy finder for neovim. You can
  use it with zoxide via the telescope-zoxide plugin.
• vim / neovim. You can use zoxide for navigation with
  the zoxide.vim (github.com) plugin.
• xxh transports your shell configuration over SSH. You can use
  zoxide over SSH via the xxh-plugin-prerun-zoxide plugin.
• zsh-autocomplete adds realtime completions to zsh. It
  supports zoxide out of the box.