zoxide 0.7.4

A smarter cd command for your terminal
zoxide-0.7.4 is not a library.

zoxide

A smarter cd command for your terminal

crates.io Releases

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.

Tutorial

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.

To install zoxide, run this command in your terminal:

curl -sS https://webinstall.dev/zoxide | bash

Alternatively, you can use a package manager:

Distribution Repository Instructions
Any crates.io cargo install zoxide
Any conda-forge conda install -c conda-forge zoxide
Any Linuxbrew brew install zoxide
Alpine Linux 3.13+ Alpine Linux Packages apk add zoxide
Arch Linux AUR yay -Sy zoxide-bin
CentOS 7+ Copr dnf copr enable atim/zoxide dnf install zoxide
Debian Testing Debian Packages apt install zoxide
Devuan 4.0+ Devuan Packages apt install zoxide
Fedora 32+ Fedora Packages dnf install zoxide
Gentoo GURU Overlay eselect repository enable guru emerge --sync guru emerge app-shells/zoxide
NixOS nixpkgs nix-env -iA nixpkgs.zoxide
Parrot OS apt install zoxide
Ubuntu 21.04+ Ubuntu Packages apt install zoxide
Void Linux Void Linux Packages xbps-install -S zoxide

To install zoxide, use a package manager:

Repository Instructions
crates.io cargo install zoxide
conda-forge conda install -c conda-forge zoxide
Homebrew brew install zoxide
MacPorts port install zoxide

To install zoxide, run this command in your command prompt:

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

Alternatively, you can use a package manager:

Repository Instructions
crates.io cargo install zoxide
Chocolatey choco install zoxide
conda-forge conda install -c conda-forge zoxide
Scoop scoop install zoxide

To install zoxide, use a package manager:

Distribution Repository Instructions
Any crates.io cargo install zoxide
DragonFly BSD DPorts pkg install zoxide
FreeBSD FreshPorts pkg install zoxide
NetBSD pkgsrc pkgin install zoxide

To install zoxide, use a package manager:

Repository Instructions
Termux pkg install zoxide

Step 2: Add zoxide to your shell

To start using zoxide, add it to your shell.

Add this to your configuration (usually ~/.bashrc):

eval "$(zoxide init bash)"

Add this to your configuration (usually ~/.elvish/rc.elv):

eval (zoxide init elvish | slurp)

Add this to your configuration (usually ~/.config/fish/config.fish):

zoxide init fish | source

Add this to your configuration (find it by running config path in Nushell):

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

You can replace __zoxide_prompt with a custom prompt.

Add this to your configuration (find it by running echo $profile in PowerShell):

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

Add this to your configuration (usually ~/.xonshrc):

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

Add this to your configuration (usually ~/.zshrc):

eval "$(zoxide init zsh)"

Add this to your configuration:

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