`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 works across all major platforms. If your distribution isn't included in the list below, you can download the binary from the Releases page and copy it to your $PATH.

On Linux

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	dm9pZCAq Overlay	`eselect repository enable dm9pZCAq` `emerge --sync dm9pZCAq` `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`

On macOS

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

On Windows

Repository	Instructions
crates.io	`cargo install zoxide`
Chocolatey	`choco install zoxide`
conda-forge	`conda install -c conda-forge 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 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)

`fish`

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

zoxide init fish | source

`nushell 0.32.0+`

Initialize zoxide's Nushell script:

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

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

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.

`powershell`

Add this to your configuration (the location is stored in $profile):

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)"

Any POSIX shell

Add this to your configuration:

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

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 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 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.

License

rizalgowandy/zoxide

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Error
Looks like something went wrong!

Packages