Blog

Zoxide: The Smarter CD Command That Actually Works

Stop typing full paths and start navigating like a pro. Zoxide learns your directory habits and gets you where you need to go faster than ever.

Zoxide: The Smarter CD Command That Actually Works

The Problem with Traditional CD

You know what’s frustrating? Typing cd /Users/username/projects/that-one-project/src/components for the twentieth time this week. Or worse—trying to remember the exact path to that configuration file you worked on last month. Traditional cd is like using a map from 1995 when you could have GPS.

Here’s the thing: your terminal should be smarter. It should learn where you go and help you get there faster. That’s exactly what zoxide does, and honestly, it’s a game-changer for anyone who spends time in the terminal.

What Makes Zoxide Special?

Zoxide isn’t just another navigation tool—it’s a learning system that adapts to your workflow. Unlike traditional cd, zoxide remembers where you’ve been and how often you visit each directory. It uses a clever algorithm that considers:

  • Frequency: How often you visit a directory
  • Recency: When you last visited it
  • Context: The current working directory when you jump

The result? You can navigate to deeply nested directories with just a few keystrokes. Instead of typing cd ~/projects/website/src/components/forms, you might just type z forms and be there instantly.

Installation: Getting Started

The installation process is straightforward, but the setup varies depending on your shell. Let me walk you through the most common scenarios.

Using the Install Script (Recommended)

The easiest way to get started is with the official install script:

curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh

This script automatically detects your shell and adds the necessary configuration. It works with bash, zsh, fish, and PowerShell.

Manual Installation

If you prefer manual installation or the script doesn’t work for your setup:

For bash/zsh:

# Add to your .bashrc or .zshrc
eval "$(zoxide init bash)"  # or zsh

For fish:

# Add to your config.fish
zoxide init fish | source

For PowerShell:

# Add to your PowerShell profile
Invoke-Expression (& { (zoxide init powershell) -join "`n" })

Basic Usage: The Z Command

Once installed, you’ll have access to the z command. Here’s how it works:

# Navigate to a directory by name
z projects

# Navigate to a subdirectory
z website/src

# Navigate to a specific file's directory
z config.json

The magic happens when you have multiple matches. Zoxide uses fuzzy matching, so z proj might take you to /Users/you/projects if that’s where you spend most of your time.

Advanced Features You’ll Actually Use

Interactive Mode with Zi

Sometimes you need to see your options before jumping. That’s where zi comes in:

zi

This opens an interactive interface (using fzf if available) where you can browse and select from your directory history. It’s perfect when you’re not sure of the exact name or when multiple directories match your query.

Adding Directories Manually

You can manually add directories to zoxide’s database:

zoxide add /path/to/directory

This is useful for directories you want to access quickly but haven’t visited yet.

Importing from Other Tools

If you’re switching from autojump or fasd, zoxide can import your existing data:

# Import from autojump
zoxide import --from=autojump ~/.local/share/autojump/autojump.txt

# Import from fasd
zoxide import --from=fasd ~/.fasd

Configuration: Making It Your Own

Zoxide is highly configurable, and you’ll want to tweak it to match your workflow.

Custom Command Names

Don’t like z? Change it:

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

You can even replace the cd command entirely:

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

Now you’d use j instead of z for navigation, or if you used --cmd cd, the cd command itself would be replaced with zoxide’s smart navigation.

Excluding Directories

Some directories just clutter your database. Exclude them:

export _ZO_EXCLUDE_DIRS="$HOME:$HOME/Downloads/*"

This prevents zoxide from learning about your home directory and download folder.

Custom FZF Options

If you use the interactive mode, customize the fzf appearance:

export _ZO_FZF_OPTS="--height=40% --border"

Real-World Usage Patterns

Here’s how zoxide fits into actual development workflows:

Project Hopping

When working on multiple projects:

z mysite    # Jump to your website project
z api       # Switch to the API project
z docs      # Open documentation

Deep Directory Navigation

Instead of cd src/components/forms/validation, just:

z validation

Configuration File Access

Quick access to config files:

z .env      # Navigate to environment file
z config    # Jump to config directory

Performance and Reliability

Zoxide is written in Rust, which means it’s fast and reliable. The database is stored locally and updates are nearly instantaneous. Unlike some alternatives, zoxide doesn’t slow down your shell startup or command execution.

The database is also cross-platform compatible, so you can sync it across machines if needed.

Integration with Other Tools

Zoxide plays nicely with other terminal tools:

  • fzf: Enhanced interactive selection
  • tmux: Works seamlessly in tmux sessions
  • neovim: Telescope integration available
  • ranger: Native support for file managers

Why You Should Switch

The main reason to use zoxide? It actually works. Unlike some tools that promise smart navigation but deliver inconsistent results, zoxide’s algorithm is genuinely intelligent. It learns your patterns and gets better over time.

Plus, it’s actively maintained, has excellent documentation, and a growing community. The 28k+ stars on GitHub aren’t just for show—people actually use this tool daily.

Getting the Most Out of Zoxide

To maximize your productivity with zoxide:

  1. Start early: Install it on new machines immediately
  2. Be consistent: Use z instead of cd for a few weeks
  3. Customize: Adjust the configuration to match your workflow
  4. Explore: Try the interactive mode and advanced features

The Bottom Line

Zoxide transforms terminal navigation from a chore into a pleasure. It’s one of those tools that, once you start using it, you can’t imagine working without. The learning curve is minimal, the benefits are immediate, and the long-term productivity gains are substantial.

If you’re still typing full paths or struggling with directory navigation, give zoxide a try. Your future self will thank you.

Resources and Further Reading

The terminal should work for you, not against you. Zoxide makes that happen.