zoxide

Modern CLI•

•Rust

Smarter cd command that learns your habits.

Official Website

Features

Smart JumpFrecency AlgorithmShell Integrationfzf Integration

Replaces

cd

Installation

Homebrew

brew install zoxide

Pacman (Arch)

pacman -S zoxide

Cargo (Rust)

cargo install zoxide

Why use zoxide?

zoxide is a smart directory jumping tool that intelligently replaces the traditionalcd command. It learns your frequently used directories and lets you jump to them instantly with partial path names.

Frecency Algorithm

Scoring based on frequency and recency automatically selects the best directory for you.

Partial Matching

Just type part of the path. z proj jumps to /home/user/projects.

Multiple Keyword Search

Narrow down paths with multiple keywords. z foo bar jumps to path containing both.

fzf Integration

Use zi command for interactive selection with fzf. Visually confirm candidates.

Installation and Setup

Shell Initialization

After installation, add initialization code to your shell configuration file.

Shell Initialization

# Bash (~/.bashrc)
eval "$(zoxide init bash)"

# Zsh (~/.zshrc)
eval "$(zoxide init zsh)"

# Fish (~/.config/fish/config.fish)
zoxide init fish | source

# PowerShell ($PROFILE)
Invoke-Expression (& { (zoxide init powershell | Out-String) })

# Nushell
# Add the following to ~/.config/nushell/config.nu
source ~/.zoxide.nu
# Run zoxide init nushell > ~/.zoxide.nu beforehand

Customize Command Name

By default the z command is used, but you can change it with the --cmd option.

Command Name Change

# Replace "cd" with zoxide
eval "$(zoxide init bash --cmd cd)"

# Use custom command name
eval "$(zoxide init bash --cmd j)"  # Jump with "j"

Basic Usage

Jump with z Command

Basic Commands

# Jump to directory (partial match)
z projects      # Jump to ~/projects
z doc           # Jump to ~/Documents

# Narrow down with multiple keywords
z my proj       # Jump to ~/my-projects
z git term      # Jump to ~/github/terminal-guide

# Full paths also work
z /var/log      # Jump to /var/log

# Jump to home directory
z               # Jump to ~

# Jump to parent directory
z ..            # Jump to parent directory

zi Command (Interactive Selection)

Interactive Selection

# Interactively select with fzf
zi

# Narrow down with keyword then select interactively
zi proj

# Narrow down with multiple keywords
zi git hub

# zi output example (fzf integration)

> ~/github/terminal-guide

~/github/my-project

~/Documents/projects

~/work/project-alpha

4/128

Common Commands

Command	Description	Example
`z <query>`	Jump to highest scoring directory	`z proj`
`zi <query>`	Interactively select with fzf	`zi doc`
`zoxide add`	Manually add directory	`zoxide add /path/to/dir`
`zoxide remove`	Remove directory from database	`zoxide remove /old/path`
`zoxide query`	Search database (don't move)	`zoxide query proj`
`zoxide query -l`	List all entries with scores	`zoxide query -l`
`zoxide query -i`	Search interactively	`zoxide query -i`
`zoxide edit`	Edit database in editor	`zoxide edit`

fzf Integration

If fzf is installed, the zi command automatically uses it.

fzf Integration

# Install fzf
brew install fzf        # macOS
apt install fzf         # Ubuntu/Debian
pacman -S fzf           # Arch Linux

# Interactive selection with zi command
zi

# Custom settings with preview
export _ZO_FZF_OPTS='--height 40% --layout=reverse --border --preview "eza -la --icons {}"'

Customize fzf Options

fzf Options Configuration

# ~/.bashrc or ~/.zshrc

# Customize fzf options
export _ZO_FZF_OPTS='
  --height=40%
  --layout=reverse
  --border
  --preview="ls -la {}"
  --preview-window=right:50%
  --bind=ctrl-d:preview-page-down
  --bind=ctrl-u:preview-page-up
'

# When eza is installed
export _ZO_FZF_OPTS='
  --height=40%
  --layout=reverse
  --border
  --preview="eza -la --icons --color=always {}"
  --preview-window=right:50%
'

Practical Examples

Using Partial Matching

Partial Matching

# Move with just part of path
z term          # ~/github/terminal-guide
z node          # ~/projects/node-app
z conf          # ~/.config

# Match by path ending
z guide         # ~/github/terminal-guide
z app           # ~/projects/my-app

# Case insensitive
z PROJ          # ~/projects
z Proj          # ~/projects

Narrow Down with Multiple Keywords

Multiple Keywords

# Narrow down candidates with multiple keywords
# Example: when ~/github/terminal-guide and ~/work/terminal-project exist

z term guide    # ~/github/terminal-guide (contains both keywords)
z term work     # ~/work/terminal-project

# More specific specification
z git term      # ~/github/terminal-guide
z hub guide     # ~/github/terminal-guide

# Order doesn't matter
z guide term    # ~/github/terminal-guide (same result as above)

Database Management

# Check current database
zoxide query -l

# Output example:
#  12.5   /home/user/github/terminal-guide
#   8.2   /home/user/projects/my-app
#   5.1   /home/user/Documents
#   3.0   /home/user/.config

# Search for specific path
zoxide query proj
# /home/user/projects/my-app

# Remove non-existent directory
# (Deleted directories are auto-removed on access, but can be done manually)
zoxide remove /old/deleted/path

# Database file location
# Linux: ~/.local/share/zoxide/db.zo
# macOS: ~/Library/Application Support/zoxide/db.zo

Using in Scripts

Script Usage

# Get path with zoxide query (without moving)
PROJECT_DIR=$(zoxide query proj)
echo "Project directory: $PROJECT_DIR"

# Temporarily move in subshell
(cd "$(zoxide query proj)" && npm run build)

# Process multiple projects
for dir in $(zoxide query -l | awk '{print $2}' | grep project); do
  echo "Processing: $dir"
  (cd "$dir" && git status)
done

Configuration and Customization

Environment Variables

# ~/.bashrc or ~/.zshrc

# Change database file path
export _ZO_DATA_DIR="$HOME/.local/share/zoxide"

# Directories to exclude (glob pattern)
export _ZO_EXCLUDE_DIRS="$HOME:$HOME/private/*:/tmp/*"

# fzf options
export _ZO_FZF_OPTS='--height 40% --layout=reverse'

# Maximum entries
export _ZO_MAXAGE=10000

# Echo mode (display destination path)
export _ZO_ECHO=1

# Resolve mode (resolve symbolic links)
export _ZO_RESOLVE_SYMLINKS=1

Environment Variable Reference

Variable	Description	Default
`_ZO_DATA_DIR`	Database storage location	OS-dependent
`_ZO_ECHO`	Display destination path	0 (disabled)
`_ZO_EXCLUDE_DIRS`	Directories to exclude	None
`_ZO_FZF_OPTS`	Options to pass to fzf	None
`_ZO_MAXAGE`	Maximum entries	10000
`_ZO_RESOLVE_SYMLINKS`	Resolve symlinks	0 (disabled)

Shell Alias Configuration

Alias Configuration

# ~/.bashrc or ~/.zshrc

# Completely replace cd
eval "$(zoxide init bash --cmd cd)"

# Additional aliases
alias zz='zi'                    # Shorter interactive jump
alias zq='zoxide query'          # Query shortcut
alias zl='zoxide query -l'       # List shortcut
alias ze='zoxide edit'           # Database edit

# Quick access to project directories
alias zp='z projects'
alias zg='z github'
alias zc='z config'

Comparison with cd

Feature	cd	zoxide
Path Specification	Full path required	Move with partial match
History Learning	-	Frecency algorithm
Multiple Keyword Search	-	Supported
Interactive Selection	-	fzf integration
Tab Completion	Path completion	Path + history completion
Speed	Fast (built-in)	Fast (Rust-built)
Database Management	-	Add/remove/edit
Shell Support	All shells	bash, zsh, fish, PowerShell, etc

Tips and Tricks

•Start by using cd to visit frequently used directories and let zoxide learn. Scores increase after a few visits
•Just typing z jumps to home directory. Use z .. to jump to parent
•Deleted directories are automatically removed from database on next access
•Set _ZO_ECHO=1 to display the full path of the destination for easy confirmation
•Migration from autojump or z.sh is possible. Use zoxide import command to migrate data
•Use zoxide query -l to check scores and verify frequently used directories are ranked high
•Built in Rust and extremely fast. No noticeable delay even when used as default instead of cd

cd Command Guide

Navigate directories

linux4 min read

fzf - Command-line Fuzzy Finder

General-purpose command-line fuzzy finder

tools10 min read

Explore More

Browse Modern CLI

See all tools in this category

All CLI Tools

Explore all tool categories

Features

Installation

Why use zoxide?

Frecency Algorithm

Partial Matching

Multiple Keyword Search

fzf Integration

Installation and Setup

Shell Initialization

Customize Command Name

Basic Usage

Jump with z Command

zi Command (Interactive Selection)

Common Commands

fzf Integration

Customize fzf Options

Practical Examples

Using Partial Matching

Narrow Down with Multiple Keywords

Database Management

Using in Scripts

Configuration and Customization

Environment Variables

Environment Variable Reference

Shell Alias Configuration

Comparison with cd

Tips and Tricks

Related Articles

cd Command Guide

fzf - Command-line Fuzzy Finder

Explore More