zoxide

A faster way to navigate your filesystem

Table of contents

• Introduction
• Examples
• Getting started
  • Installing zoxide
  • Installing fzf (optional)
  • Adding zoxide to your shell
  • bash
  • fish
  • POSIX
  • PowerShell
  • xonsh
  • zsh
• Configuration
  • init flags
  • Environment variables

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

```sh 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

zq foo # echo the best match, don't cd

za /foo # add /foo to the database zr /foo # remove /foo from the database ```

Getting started

Step 1: Installing zoxide

On Arch Linux

sh yay -S zoxide

On CentOS

sh dnf copr enable atim/zoxide dnf install zoxide

On DragonFly BSD

sh pkg install zoxide

On Fedora 32+

sh dnf install zoxide

On FreeBSD

sh pkg install zoxide

On macOS / Linux (via Homebrew / Linuxbrew)

sh brew install zoxide

On macOS (via MacPorts)

sh port install zoxide

On NixOS

sh nix-env -iA nixpkgs.zoxide

On Void Linux

sh xbps-install -S zoxide

On Windows (via Scoop)

powershell scoop install zoxide

Other (via Cargo)

sh cargo install zoxide -f

Other (via precompiled binary)

Use the installation script:

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

Alternatively, you can also download a precompiled binary from the releases page and add it to your PATH.

Step 2: Installing fzf (optional)

If you want to use interactive fuzzy selection, you will also need to install fzf.

Step 3: Adding zoxide to your shell

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

sh zoxide import /path/to/db

bash

Add the following line to your ~/.bashrc:

sh eval "$(zoxide init bash)"

fish

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

sh zoxide init fish | source

POSIX shells

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

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

PowerShell

Add the following line to your profile:

powershell 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):

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

zsh

Add the following line to your ~/.zshrc:

sh eval "$(zoxide init zsh)"

Configuration

init flags

• --cmd: change the z command (and corresponding aliases) to something else
• --hook <HOOK>: change the event that adds a new entry to the database (default: pwd)
  • none: never add entries (this will make zoxide useless unless you manually configure a hook)
  • prompt: add an entry at every prompt
  • pwd: add an entry whenever the current directory is changed
• --no-aliases: don't define extra aliases like zi, zq, za, and zr

Environment variables

• $_ZO_DATA_DIR: directory where zoxide will store its data files (default: platform-specific; see the [dirs documentation] for more information)
• $_ZO_ECHO: when set to 1, z will print the matched directory before navigating to it
• $_ZO_EXCLUDE_DIRS: list of directories separated by platform-specific characters (":" on Linux/macOS, ";" on Windows) to be excluded from the database
• $_ZO_FZF_OPTS: custom flags to pass to fzf
• $_ZO_MAXAGE: sets the maximum total age after which entries start getting deleted
• $_ZO_RESOLVE_SYMLINKS: when set to 1, z add will resolve symlinks.