Skip to main content

zoxide — Smarter cd with Fuzzy Directory Jumping

zoxide is a fast, smarter replacement for manual cd navigation.

It learns the directories you visit and lets you jump back to them using short fuzzy keywords.

Instead of typing:

cd /var/www/html/wp-content/uploads

You can type:

z uploads

And jump instantly.

1. What zoxide Does

  • Tracks directories you visit
  • Ranks them by frequency and recency
  • Lets you jump using fuzzy matching
  • Works across shell sessions
  • Integrates into bash, zsh, fish, and others

It does not replace cd by default — it enhances navigation.

2. Installation

Ubuntu/Debian​

sudo apt install zoxide

Initialize in Bash​

echo 'eval "$(zoxide init bash)"' >> ~/.bashrc
exec bash

Verify​

zoxide --version
command -v z

After initialization, you get:

  • z → jump
  • zi → interactive jump (requires fzf)

3. Core Syntax

Everyday Commands (after init)​

z [KEYWORDS...]
zi [KEYWORDS...]

Low-Level Commands​

zoxide query [OPTIONS] [KEYWORDS...]
zoxide add <DIR>
zoxide remove <DIR>
zoxide init <SHELL>

4. Core Behavior

z​

Jumps to the best matching directory based on ranking.

z uploads

zi​

Interactive fuzzy selection (requires fzf).

zi wp

5. Important Commands & Options

CommandPurpose
---
z keywordJump to best match
zi keywordInteractive picker
zoxide queryPrint best match (no jump)
zoxide query -lList ranked matches
zoxide add DIRManually add/boost a directory
zoxide remove DIRRemove directory from database
zoxide init bash --cmd jRename z to j
zoxide init bash --hook pwdUpdate DB only on directory change

6. Useful Environment Variables

Set these in your shell config if needed.

Exclude Directories​

export _ZO_EXCLUDE_DIRS="**/node_modules:**/vendor"

Prevents polluting the database.

export _ZO_RESOLVE_SYMLINKS=1

Stores canonical real paths (useful in WordPress deployments with current symlink).

Custom Database Location​

export _ZO_DATA_DIR="$HOME/.local/share/zoxide"

Adjust Aging​

export _ZO_MAXAGE=10000

Controls how quickly unused entries decay.

7. WordPress VPS Use Cases

Assume WordPress root:

/var/www/html

Jump to uploads instantly​

z uploads

Goes to:

/var/www/html/wp-content/uploads

Jump to themes​

z themes

Jump to Nginx logs​

z nginx

If you've visited /var/log/nginx, it jumps there.

Interactive plugin selection​

zi plugin

Choose from multiple plugin directories.

Preview matches​

zoxide query -l wp

Shows ranked directories matching wp.

Seed WordPress root​

zoxide add /var/www/html

Boost its ranking.

Remove stale deployment​

zoxide remove /var/www/html/releases/old-release

Keeps database clean.

Rename command to j​

eval "$(zoxide init bash --cmd j)"

Use:

j uploads

Replace cd (where supported)​

eval "$(zoxide init zsh --cmd cd)"

Now:

cd uploads

Has fuzzy power.

Use in script​

TARGET=$(zoxide query wp)
echo "$TARGET"

Retrieve best match without jumping.

8. How Ranking Works

zoxide ranks directories based on:

  • Frequency of visits
  • Recency
  • Path score
  • Aging factor

More visits → higher priority.

9. Best Practices

  • Add zoxide init at end of .bashrc or .zshrc
  • Exclude heavy folders like node_modules
  • Use zi when unsure
  • Use z when confident
  • Enable _ZO_RESOLVE_SYMLINKS=1 in deployment-based WordPress setups
  • Keep database clean with zoxide remove

10. Troubleshooting

z: command not found​

Initialization missing.

Add to shell config:

eval "$(zoxide init bash)"

zi does nothing​

Install fzf:

sudo apt install fzf

Jump goes to wrong directory​

  • Too many similar matches
  • Exclude noisy directories
  • Use zi instead

Performance issues​

Use:

zoxide init bash --hook pwd

Reduces update frequency.

11. Cheat Sheet

z keyword                 # jump
zi keyword                # interactive jump
zoxide query keyword      # show best match
zoxide query -l keyword   # list matches
zoxide add DIR            # add directory
zoxide remove DIR         # remove directory

# Tuning
export _ZO_EXCLUDE_DIRS="**/node_modules:**/vendor"
export _ZO_RESOLVE_SYMLINKS=1
eval "$(zoxide init bash --hook pwd)"

12. Mini Quiz

  1. What does z uploads do?
  2. What is the difference between z and zi?
  3. How do you preview matches without changing directories?
  4. How do you exclude vendor folders globally?
  5. Why might _ZO_RESOLVE_SYMLINKS=1 be useful in WordPress deployments?

Summary

zoxide is:

  • A smart directory jumper
  • Faster than manual cd
  • Persistent across sessions
  • Perfect for repetitive VPS navigation
  • Ideal for WordPress maintenance workflows