A smarter cd command. Supports all major shells.
Go to file
2021-04-16 15:31:11 +05:30
.github/workflows Release v0.6.0 2021-04-09 00:50:55 +05:30
contrib Use Nushell from Nixpkgs unstable (#171) 2021-04-05 12:01:24 +05:30
man Performance improvements for queries (#185) 2021-04-16 15:31:11 +05:30
src Performance improvements for queries (#185) 2021-04-16 15:31:11 +05:30
templates Fix cd - on fish (#179) 2021-04-13 01:57:36 +05:30
.gitignore Fix CI (#161) 2021-03-29 21:14:30 +05:30
build.rs Update README 2021-02-02 00:11:07 +05:30
Cargo.lock Release v0.6.0 2021-04-09 00:50:55 +05:30
Cargo.toml Performance improvements for queries (#185) 2021-04-16 15:31:11 +05:30
CHANGELOG.md Performance improvements for queries (#185) 2021-04-16 15:31:11 +05:30
demo.gif Add demo GIF to README 2020-05-30 05:08:30 +05:30
init.fish * Add init subcommand for bash, fish, and zsh 2020-03-11 00:14:50 +05:30
install.sh Release v0.4.1 2020-05-25 02:55:00 +05:30
LICENSE Initial commit 2020-03-05 20:06:58 +05:30
Makefile Use Nushell from Nixpkgs unstable (#171) 2021-04-05 12:01:24 +05:30
README.md Performance improvements for queries (#185) 2021-04-16 15:31:11 +05:30
shell.nix Add support for Elvish (#174) 2021-04-09 00:05:42 +05:30
zoxide.plugin.zsh * Add init subcommand for bash, fish, and zsh 2020-03-11 00:14:50 +05:30

zoxide

crates.io

A smarter cd command

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.

Demo

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 works across all major platforms. If your distribution isn't included in the list below, you can directly install the binary from GitHub:

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh

If you would rather not run a script, you can download the binary from the Releases page and add it to your $PATH.

On Linux

Distribution Repository Instructions
Any crates.io cargo install zoxide
Any Linuxbrew brew install zoxide
Alpine Linux Alpine Linux Packages apk add zoxide
Arch Linux AUR yay -Sy zoxide-bin
CentOS Copr dnf copr enable atim/zoxide
dnf install zoxide
Debian Testing Debian Packages apt install zoxide
Fedora Fedora Packages dnf install zoxide
NixOS nixpkgs nix-env -iA nixpkgs.zoxide
Parrot OS apt install zoxide
Void Linux Void Linux Packages xbps-install -S zoxide

On macOS

Repository Instructions
crates.io cargo install zoxide
Homebrew brew install zoxide
MacPorts port install zoxide

On Windows

Repository Instructions
crates.io cargo install zoxide
Scoop scoop install zoxide

On BSD

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

On Android

Repository Instructions
Termux pkg install zoxide

Step 2: Install fzf (optional)

fzf is a command-line fuzzy finder, used by zoxide for interactive selection. Installation instructions can be found here.

Step 3: Add zoxide to your shell

If you currently use z, z.lua, or zsh-z, you may want to first import your existing entries into zoxide:

zoxide import --from z path/to/db

Alternatively, for autojump (note that scores are not imported):

zoxide import --from autojump path/to/db

bash

Add the following line to your configuration file (usually ~/.bashrc):

eval "$(zoxide init bash)"

elvish

Add the following line to your configuration file (usually ~/.elvish/rc.elv):

eval $(zoxide init elvish | slurp)

fish

Add the following line to your configuration file (usually ~/.config/fish/config.fish):

zoxide init fish | source

nushell

Initialize zoxide's Nushell script:

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

Then, in your Nushell configuration file:

  • Prepend __zoxide_hook; to the prompt variable.
  • Add the following lines to the startup variable:
    • zoxide init nushell --hook prompt | save ~/.zoxide.nu
    • source ~/.zoxide.nu

powershell

Add the following line to your profile:

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

xonsh

Add the following line to your configuration file (usually ~/.xonshrc):

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

zsh

Add the following line to your configuration file (usually ~/.zshrc):

eval "$(zoxide init zsh)"

Any POSIX shell

Add the following line to your configuration file (usually ~/.config/nu/config.toml):

eval "$(zoxide init posix --hook prompt)"

Configuration

init flags

  • --cmd: changes the prefix of predefined aliases (z, zi).
    • e.g. --cmd j would change the aliases to j and ji respectively.
  • --hook <HOOK>: change how often zoxide increments a directory's score:
    • none: never automatically add directories to zoxide.
    • prompt: add the current directory to zoxide at every shell prompt.
    • pwd: whenever the user changes directories, add the new directory to zoxide.
  • --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 use them elsewhere.

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/*
  • _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