Zoxide Tutorial: Navigate Your Terminal 10x Faster

Zoxide is a smarter cd replacement that learns your most-used directories and lets you jump to them instantly. If you spend more than a few seconds navigating your terminal each day, this tool will change how you work.

At ProductivityTech, we've tested dozens of terminal productivity tools. Zoxide stands out because it requires zero configuration, works across every major shell, and delivers measurable time savings from day one. In this zoxide tutorial, we walk you through installation, core commands, and real workflows that make terminal navigation effortless.

The Hidden Cost of cd

Every developer types cd hundreds of times per day. A quick study by shell history analysis tools shows that cd is consistently one of the top 5 most-used terminal commands.

Here's the math. If you type 50 directory changes per day and each one takes 5 seconds — remembering the path, tab-completing, fixing typos — that's over 4 minutes daily. Over a year, that adds up to 17+ hours spent just navigating directories.

Zoxide eliminates most of that friction by learning which directories you visit and letting you jump to them with a few keystrokes.

What Is Zoxide?

Zoxide is an open-source command-line tool written in Rust that replaces the traditional cd command. It uses a frecency algorithm — a combination of frequency and recency — to rank your most-used directories.

Type z project and zoxide instantly jumps to ~/work/client-projects/project-alpha because that's where you go most often. No full paths. No tab completion chains. Just type a fragment and go.

Key features:

• Frecency ranking — frequently and recently visited directories rank higher
• Fuzzy matching — partial directory names work out of the box
• Cross-shell support — works with zsh, bash, fish, PowerShell, and more
• Written in Rust — blazingly fast with zero runtime dependencies
• 21k+ GitHub stars — actively maintained and widely adopted

How to Install Zoxide

Installation takes less than 60 seconds on any platform.

macOS (Homebrew)

brew install zoxide

Linux (apt)

sudo apt install zoxide

Any Platform (Cargo)

cargo install zoxide --locked

Shell Integration

After installing, add the init command to your shell config:

Zsh (~/.zshrc):

eval "$(zoxide init zsh)"

Bash (~/.bashrc):

eval "$(zoxide init bash)"

Fish (~/.config/fish/config.fish):

zoxide init fish | source

Restart your shell or run source ~/.zshrc, and you're ready to go.

Zoxide Core Commands You Need

Zoxide gives you two main commands: z and zi. That's all you need for 95% of use cases.

z — Smart Jump

The basic command. Type z followed by a partial directory name:

z projects     # jumps to ~/work/projects
z api          # jumps to ~/work/my-app/src/api
z note         # jumps to ~/Documents/notes

Zoxide matches against your directory history and picks the highest-ranked result. Chain multiple fragments for precision:

z work api     # jumps to ~/work/my-app/src/api (not ~/personal/api)

zi — Interactive Selection

When multiple directories match, zi opens an interactive fuzzy finder (requires fzf):

zi project

This shows a filterable list of all matching directories. Use arrow keys to pick the right one. It's the perfect fallback when z alone isn't specific enough.

zoxide query

View your full directory database:

zoxide query --list       # list all tracked directories
zoxide query --list -s    # sorted by score
zoxide query project      # show matches for "project"

Alias to j (Optional)

Many developers alias z to j (for "jump") to avoid conflicts:

alias j='z'
alias ji='zi'

Zoxide vs Autojump vs z vs fasd

Zoxide isn't the first smart cd tool, but it's the best one available in 2026. Here's how it compares:

Feature	Zoxide	Autojump	z (rupa)	fasd
Language	Rust	Python	Shell	Shell
Speed	⚡ Fastest	Slow	Fast	Moderate
Maintained	✅ Active	❌ Archived	⚠️ Minimal	❌ Archived
Shell support	zsh, bash, fish, PowerShell, Nushell, Elvish	zsh, bash, fish	zsh, bash	zsh, bash
Interactive mode	✅ (fzf)	❌	❌	✅
GitHub stars	21k+	16k	16k	6k
Install size	~2 MB	~50 MB (Python)	~5 KB	~10 KB

The verdict: Autojump and fasd are both archived and no longer maintained. The original z still works but lacks interactive mode and cross-shell support. Zoxide is the only actively maintained option with modern features, and it's the fastest by a significant margin.

If you're currently using autojump, migrating is straightforward:

zoxide import --from autojump

This imports your existing directory database so you don't lose your history.

Real Workflows That Save Time

Here are practical zoxide workflows that go beyond the basics.

Jump to Repos Instantly

If you work across multiple Git repositories, zoxide learns them all:

z mentorkit     # ~/work/mentorkit-lms-pro
z theme         # ~/work/productivitytech-theme
z dotfiles      # ~/.dotfiles

No more cd ~/work/clients/acme/repos/frontend. Just z frontend.

Combine With fzf for Power Selection

Install fzf alongside zoxide for the ultimate navigation experience:

brew install fzf

Now zi gives you a full interactive directory picker with fuzzy search, preview, and keyboard navigation.

VS Code Integrated Terminal

Zoxide works seamlessly inside VS Code's built-in terminal. Open a new terminal panel and use z to jump between project directories without leaving your editor. This is especially powerful when working on monorepos or microservice architectures.

Pipe Into Other Commands

Combine zoxide with other tools:

ls $(zoxide query project)    # list files in a matched directory
code $(zoxide query theme)    # open a project in VS Code

Zoxide Tips and Configuration

Fine-tune zoxide with environment variables in your shell config.

Exclude Directories

Keep certain paths out of the database:

export _ZO_EXCLUDE_DIRS="/tmp:/private/var"

Limit Database Size

Control how many directories zoxide remembers:

export _ZO_MAXAGE=10000    # default is 10000

Custom Data Directory

Store the database in a specific location:

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

Pro Tips

1. Use it for a week before judging — zoxide needs time to learn your habits. After 3–5 days, it becomes remarkably accurate.
2. Don't fight the ranking — if zoxide picks the wrong directory, just cd to the right one manually. It will learn from the correction.
3. Combine fragments — z work api is more precise than z api. Use multiple fragments to disambiguate.
4. Clean stale entries — run zoxide query --list periodically and remove deleted directories with zoxide remove /old/path.

Frequently Asked Questions

---

Zoxide is one of those tools that takes 60 seconds to install and saves you hours over time. If you spend any time in the terminal, it's a no-brainer upgrade over cd.

Ready to get started? Run brew install zoxide, add the init line to your shell config, and start navigating. Within a week, you'll wonder how you ever worked without it.