Zoxide: 36,752 GitHub Stars — Complete Setup Guide 2026

{{< resource-info >}}

The average developer changes directories 200+ times per day. If each cd command costs you 3-5 seconds of typing full paths, that is 10-15 minutes lost daily to navigation alone. Zoxide eliminates this friction entirely: it learns where you go and lets you jump there with two keystrokes. With 36,752 GitHub stars and a Rust-powered core, it has become the de facto replacement for the traditional cd command across the developer community.

This guide covers everything you need to install, configure, and production-harden Zoxide on any platform and shell — with real configs, benchmarks, and migration paths from autojump and fasd.

What Is Zoxide? #

Zoxide (pronounced “zoh-kside”) is a cross-shell directory jumper written in Rust. It tracks the directories you visit, assigns each a relevance score based on frequency and recency (a metric called “frecency”), and lets you navigate to them using fuzzy keyword matches instead of full paths.

If you have visited ~/projects/mycompany/frontend/src/components three times today, typing z comp or even z fro src will teleport you there instantly. No aliases. No bookmarks. No memorization.

How Zoxide Works #

The Frecency Algorithm #

Zoxide ranks directories using frecency — a blend of frequency and recency. Each directory starts with a score of 1 on first access. Every subsequent visit increments the score by 1. When you query, the score is weighted by how recently the directory was accessed:

This means a directory you visited 20 times but not in the last month may rank lower than one you visited 5 times this morning.

Matching Rules #

Zoxide uses predictable, case-insensitive matching:

• All query terms must appear in the path in order.
• z fo ba matches /foo/bar but not /bar/foo.
• The last term must match the final path component.
• z bar matches /foo/bar but not /bar/foo.
• Slashes are literal: z fo / ba matches /foo/bar but not /foobar.

Database Management #

Zoxide stores its database at platform-specific paths:

The database auto-prunes entries that no longer exist on disk and are older than 90 days. The _ZO_MAXAGE variable (default 10000) caps total entries via an aging algorithm that scales scores down when the threshold is exceeded.

Installation and Setup #

Step 1: Install the Binary #

Linux / WSL (universal install script):

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

macOS (Homebrew):

brew install zoxide

Arch Linux:

sudo pacman -S zoxide

Fedora / RHEL:

sudo dnf install zoxide

Ubuntu / Debian (24.04+):

sudo apt install zoxide

Windows (winget):

winget install ajeetdsouza.zoxide

Windows (Scoop):

scoop install zoxide

Via Cargo (any platform with Rust):

cargo install zoxide --locked

Verify the installation:

zoxide --version
# zoxide 0.9.7

Step 2: Add Shell Integration #

Zoxide requires a one-time initialization in your shell config. This enables the z and zi commands and hooks into directory changes to update the database.

Bash — add to ~/.bashrc:

eval "$(zoxide init bash)"

Zsh — add to ~/.zshrc (after compinit):

eval "$(zoxide init zsh)"

Fish — add to ~/.config/fish/config.fish:

zoxide init fish | source

Nushell — add to your env file ($nu.env-path):

zoxide init nushell | save -f ~/.zoxide.nu

Then source it in your config file ($nu.config-path):

source ~/.zoxide.nu

PowerShell — add to your profile (find it with echo $profile):

Invoke-Expression (& { (zoxide init powershell | Out-String) })

Reload your shell or source the config:

source ~/.bashrc   # or ~/.zshrc, etc.

Step 3: Install fzf (Optional but Recommended) #

The zi command provides interactive fuzzy selection powered by fzf:

# macOS
brew install fzf

# Ubuntu/Debian
sudo apt install fzf

# Arch
sudo pacman -S fzf

# Or via git
 git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
~/.fzf/install

Step 4: Import Existing Data (Optional) #

If you are migrating from another directory jumper, import your history:

# From autojump
zoxide import autojump

# From fasd
zoxide import fasd

# From z or z.lua
zoxide import z

# From Atuin
zoxide import atuin

Integration with Popular Tools #

fzf Interactive Selection #

With fzf installed, zi opens an interactive fuzzy finder over your directory history:

zi frontend        # fuzzy-find any directory matching "frontend"
zi                 # browse entire directory history

Customize fzf behavior for zoxide:

export _ZO_FZF_OPTS="--height 40% --reverse --preview 'ls -la {}'"

nnn File Manager #

Zoxide integrates natively with nnn via the nnn-autojump plugin. Add to your nnn configuration:

export NNN_PLUG="z:zoxide"

Then press ;z in nnn to jump with zoxide.

tmux Session Managers #

Tools like sesh, tmux-session-wizard, and tmux-sessionx support zoxide natively for launching tmux sessions from your most-used directories:

# With sesh installed
sesh list          # shows zoxide-ranked directories
sesh connect       # interactive tmux session from zoxide list

Neovim / Vim #

Use telescope-zoxide for fuzzy directory navigation inside Neovim:

-- In your Neovim config (Lazy.nvim)
{
  "jvgrootvelte/telescope-zoxide",
  dependencies = { "nvim-telescope/telescope.nvim" },
  config = function()
    require("telescope").load_extension("zoxide")
  end,
}

Trigger with :Telescope zoxide list.

Yazi File Manager #

Yazi supports zoxide natively. Press Z in Yazi to trigger zoxide directory jumping.

Emacs #

Install zoxide.el from MELPA:

(use-package zoxide
  :ensure t
  :bind (("C-c z" . zoxide-find-file)))

Benchmarks and Real-World Use Cases #

Startup and Query Performance #

Measured on a Ryzen 9 5900X with SSD and 10,000 tracked directories.

Daily Time Savings #

Team-Wide Adoption at Scale #

A 50-engineer team adopting Zoxide saves an estimated 10+ hours of navigation time per day collectively — time redirected toward actual development work. The learning curve is negligible; most developers are productive within 5 minutes of installation.

Advanced Usage and Production Hardening #

Replace cd Entirely #

To make cd itself use zoxide, initialize with --cmd cd:

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

Now cd proj behaves like z proj for fuzzy matching, while still supporting native cd syntax for absolute paths.

Custom Aliases #

eval "$(zoxide init bash --cmd j)"    # use j/ji instead of z/zi

Exclude Directories #

Prevent zoxide from tracking sensitive or temporary directories:

export _ZO_EXCLUDE_DIRS="$HOME:$HOME/private/*:/tmp:/var/tmp"

On Windows, use semicolons as separators:

$env:_ZO_EXCLUDE_DIRS = "$HOME;$HOME\private\*;C:\Temp"

Change Database Location #

export _ZO_DATA_DIR="/mnt/fast-ssd/zoxide-data"

Enable Echo Mode #

Print the matched directory before navigating (useful for scripting):

export _ZO_ECHO=1

Resolve Symlinks #

If you work in symlinked environments, force symlink resolution before database writes:

export _ZO_RESOLVE_SYMLINKS=1

Hook Configuration #

Control when zoxide updates directory scores:

eval "$(zoxide init bash --hook prompt)"   # update at every prompt
eval "$(zoxide init bash --hook pwd)"      # update only on cd (default)
eval "$(zoxide init bash --hook none)"     # never auto-update; use zoxide add manually

Database Maintenance #

# View all tracked directories with scores
zoxide query --list --score

# Remove a specific directory
zoxide remove /old/project/path

# Clean up after deleting projects
zoxide edit                    # opens database in $EDITOR

Shell Completion Setup #

Zsh — ensure the init line is placed after compinit:

autoload -Uz compinit; compinit
eval "$(zoxide init zsh)"      # must come AFTER compinit
rm ~/.zcompdump*; compinit     # rebuild completion cache if needed

Bash 4.4+ — z <query><SPACE><TAB> triggers interactive completions.

Comparison with Alternatives #

Zoxide wins on every metric except raw startup time against native cd — and even that is a non-issue since the z command is only invoked when you need smart matching. For absolute paths, zoxide delegates to the shell’s built-in cd.

Limitations and Honest Assessment #

Zoxide is not a universal cd replacement. There are specific scenarios where it adds no value:

• CI/CD pipelines: Scripts should use absolute paths or cd for determinism. Zoxide’s database-dependent behavior introduces non-reproducibility.
• Shared systems / multi-user servers: The database is per-user by design. It does not help with discovering directories you have never visited.
• Very short paths: Typing z d to reach /home/user/Downloads saves no keystrokes over cd ~/D + Tab.
• First-time navigation: Zoxide only knows directories you have already visited at least once. The first visit requires a normal cd or absolute path.
• Non-interactive shells: In subshells and non-login shells, database initialization adds a small (~5ms) overhead that may matter in high-frequency script loops.
• Database corruption risk: Although SQLite is robust, force-killing shells during writes could theoretically corrupt the database. Keep backups of _ZO_DATA_DIR if you rely heavily on the history.

Frequently Asked Questions #

Does Zoxide work with all shells? #

Yes. Zoxide officially supports Bash, Zsh, Fish, Nushell, PowerShell, Elvish, Tcsh, Xonsh, and any POSIX-compliant shell. The init command generates shell-specific code for each.

Can I use Zoxide alongside my existing cd command? #

Absolutely. By default, z and zi are separate commands that do not interfere with cd. If you want cd itself to use zoxide’s smart matching, initialize with --cmd cd.

How do I migrate from autojump or fasd? #

Use the built-in import commands: zoxide import autojump, zoxide import fasd, zoxide import z, etc. These auto-detect the source database format and convert entries to zoxide’s SQLite format.

Where is my data stored and can I back it up? #

The database is a single SQLite file at ~/.local/share/zoxide/db.sqlite on Linux, ~/Library/Application Support/zoxide/db.sqlite on macOS, and %LOCALAPPDATA%\\zoxide\\db.sqlite on Windows. Copy that file to back up your directory history.

Does Zoxide work on Windows? #

Yes. Zoxide has first-class Windows support via winget, Scoop, Chocolatey, and Cargo. It works in PowerShell, Command Prompt (via Clink), Git Bash, MSYS2, and WSL.

Can I use Zoxide without fzf? #

Yes. The core z command works without fzf. fzf is only needed for the zi interactive selection feature and tab completions. If you skip fzf, you still get 90% of zoxide’s value.

How does Zoxide handle directories with the same name? #

It ranks them by frecency score. If you have both ~/work/frontend and ~/personal/frontend, the one you visited more recently and frequently wins. Use z work fro or z per fro to disambiguate.

Is the database encrypted? #

No. The SQLite database stores plaintext paths. If directory names contain sensitive information, set _ZO_EXCLUDE_DIRS to exclude those paths from tracking.

Can I disable database updates for specific sessions? #

Set _ZO_DATA_DIR to a temporary location or use --hook none during initialization and manually run zoxide add only when needed.

Conclusion #

Zoxide is the most mature, performant, and well-maintained directory jumper available in 2026. Installation takes under 60 seconds, the learning curve is flat, and the daily time savings are measurable. If you are still typing full paths with cd, you are leaving productivity on the table.

Action items:

1. Install Zoxide using your platform’s package manager (see Installation section).
2. Add the single eval line to your shell config.
3. Install fzf for the zi interactive experience.
4. Import data from autojump/fasd if migrating.
5. Join the discussion: share your Zoxide tips in our Telegram group.

Recommended Hosting & Infrastructure #

Before you deploy any of the tools above into production, you’ll need solid infrastructure. Two options dibi8 actually uses and recommends:

• DigitalOcean — $200 free credit for 60 days across 14+ global regions. The default option for indie devs running open-source AI tools.
• HTStack — Hong Kong VPS with low-latency access from mainland China. This is the same IDC that hosts dibi8.com — battle-tested in production.

Affiliate links — they don’t cost you extra and they help keep dibi8.com running.

Sources and Further Reading #

• Zoxide GitHub Repository
• Zoxide Algorithm Documentation
• Zoxide Official Website
• fzf GitHub Repository
• telescope-zoxide for Neovim
• Zoxide NixOS Wiki
• navi Cheat Sheets with Zoxide