zoxide/README.md

zoxide

A faster way to navigate your filesystem

Table of contents

• Introduction
• Examples
• Getting started
  • Step 1: Install zoxide
  • Step 2: Install fzf (optional)
  • Step 3: Add zoxide to your shell
• Configuration

Introduction

zoxide is a blazing fast alternative to cd, 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 to highest ranked directory matching foo
z foo bar   # cd to highest ranked directory matching foo and bar

z foo/      # can also cd into actual directories

zi foo      # cd with interactive selection using fzf

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/master/install.sh | sh

If you would rather not run a script, you can download the binary from the Releases page and add it anywhere in 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 /path/to/db

Alternatively, for autojump:

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

bash

Add the following line to your ~/.bashrc:

eval "$(zoxide init bash)"

fish

Add the following line to your ~/.config/fish/config.fish:

zoxide init fish | source

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 profile (usually ~/.xonshrc):

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

zsh

Add the following line to your ~/.zshrc:

eval "$(zoxide init zsh)"

Any POSIX shell

Add the following line to your shell's configuration file:

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

• _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 Unix 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

• xxh, via xxh-plugin-prerun-zoxide
• nnn, via autojump plugin