#cli

app zoxide

A smarter cd command for your terminal

26 releases

Uses new Rust 2021

0.8.2 Jun 25, 2022
0.8.0 Dec 24, 2021
0.7.9 Nov 1, 2021
0.7.2 Jun 10, 2021
0.3.0 Mar 30, 2020

#3 in Command line utilities

Download history 964/week @ 2022-04-22 785/week @ 2022-04-29 601/week @ 2022-05-06 390/week @ 2022-05-13 308/week @ 2022-05-20 348/week @ 2022-05-27 348/week @ 2022-06-03 248/week @ 2022-06-10 288/week @ 2022-06-17 671/week @ 2022-06-24 550/week @ 2022-07-01 398/week @ 2022-07-08 311/week @ 2022-07-15 357/week @ 2022-07-22 353/week @ 2022-07-29 278/week @ 2022-08-05

1,349 downloads per month

MIT license

135KB
2K SLoC

Rust 1.5K SLoC // 0.0% comments TypeScript 195 SLoC BASH 136 SLoC PowerShell 84 SLoC Elvish 76 SLoC Zsh 5 SLoC

zoxide

crates.io Downloads License Built with Nix

zoxide is a smarter cd command, inspired by z and autojump.

It remembers which directories you use most frequently, so you can "jump" to them in just a few keystrokes.
zoxide works on all major shells.

Getting startedInstallationConfigurationIntegrations

Getting started

Tutorial

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.

Linux

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 --locked
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 Arch Linux Community pacman -S zoxide
CentOS 7+ Copr dnf copr enable atim/zoxide
dnf install zoxide
Debian 11+ 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
Manjaro pacman -S zoxide
NixOS nixpkgs nix-env -iA nixpkgs.zoxide
Parrot OS apt install zoxide
Raspbian 11+ Raspbian Packages apt install zoxide
Ubuntu 21.04+ Ubuntu Packages apt install zoxide
Void Linux Void Linux Packages xbps-install -S zoxide
macOS

To install zoxide, use a package manager:

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

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 --locked
Chocolatey choco install zoxide
conda-forge conda install -c conda-forge zoxide
Scoop scoop install zoxide
BSD

To install zoxide, use a package manager:

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

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.

Bash

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

eval "$(zoxide init bash)"
Elvish

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

eval (zoxide init elvish | slurp)

Note: zoxide only supports elvish v0.18.0 and above.

Fish

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

zoxide init fish | source
Nushell

Add this to your env file (find it by running $nu.env-path in Nushell):

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

Now, add this to the end of your config file (find it by running $nu.config-path in Nushell):

source ~/.zoxide.nu

Note: zoxide only supports Nushell v0.61.0 and above.

PowerShell

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

# 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"
})
Xonsh

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

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

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

eval "$(zoxide init zsh)"

For completions to work, the above line must be added after compinit is called. You may have to rebuild your cache by running rm ~/.zcompdump*; compinit.

Any POSIX shell

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.

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:

autojump
zoxide import --from autojump path/to/db

The default path varies according to your system:

OS Path Example
Linux $XDG_DATA_HOME/autojump/autojump.txt or $HOME/.local/share/autojump/autojump.txt /home/alice/.local/share/autojump/autojump.txt
macOS $HOME/Library/autojump/autojump.txt /Users/Alice/Library/autojump/autojump.txt
Windows %APPDATA%\autojump\autojump.txt C:\Users\Alice\AppData\Roaming\autojump\autojump.txt
z, z.lua, or zsh-z
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

Application Description Plugin
clink Improved cmd.exe for Windows clink-zoxide
emacs Text editor zoxide.el
felix File manager Natively supported
joshuto File manager Natively supported
lf File manager See the wiki
nnn File manager nnn-autojump
ranger File manager ranger-zoxide
telescope.nvim Fuzzy finder for Neovim telescope-zoxide
vim Text editor zoxide.vim
xplr File manager zoxide.xplr
xxh Transports shell configuration over SSH xxh-plugin-prerun-zoxide
zabb Finds the shortest possible query for a path Natively supported
zsh-autocomplete Realtime completions for zsh Natively supported

Dependencies

~4–5MB
~102K SLoC