A smarter cd command that learns your most-used directories and lets you jump to them with just a few keystrokes. Uses a “frecency” algorithm combining frequency and recency of visits.
| Platform | Command |
|---|
| macOS (Homebrew) | brew install zoxide |
| Ubuntu/Debian | sudo apt install zoxide |
| Arch Linux | sudo pacman -S zoxide |
| Fedora/RHEL | sudo dnf install zoxide |
| Windows (Winget) | winget install ajeetdsouza.zoxide |
| Windows (Scoop) | scoop install zoxide |
| Windows (Chocolatey) | choco install zoxide |
| Cargo (All platforms) | cargo install zoxide --locked |
| Conda | conda install -c conda-forge zoxide |
| Nix | nix-env -iA nixpkgs.zoxide |
| Install script | curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh |
Add the appropriate line to your shell config file:
| Shell | Config File | Command to Add |
|---|
| 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) }) |
| Elvish | ~/.elvish/rc.elv | eval (zoxide init elvish | slurp) |
| Nushell | env.nu | zoxide init nushell | save -f ~/.zoxide.nu |
| Xonsh | ~/.xonshrc | execx($(zoxide init xonsh)) |
| Command | Description |
|---|
z foo | Jump to highest-ranked directory matching “foo” |
z foo bar | Jump to directory matching both “foo” and “bar” |
z ~/projects | Jump to exact path (works like regular cd) |
z .. | Go up one directory |
z - | Return to previous directory |
zi foo | Interactive selection with fzf (when multiple matches) |
zi | Interactive selection from all tracked directories |
zoxide matches directory paths by keywords. You don’t need to type the full path:
# If you frequently visit /home/user/projects/my-app
z my-app # Jumps directly there
z proj app # Also works (matches both words in path)
z app # Works if it's your most frequent "app" directory
Scoring: Directories get points when visited. Recent visits score higher. Unused directories decay over time.
| Command | Description |
|---|
zoxide add /path/to/dir | Manually add a directory to the database |
zoxide remove /path/to/dir | Remove a directory from the database |
zoxide edit | Open database in $EDITOR for manual editing |
zoxide query foo | Show the best match for “foo” (without jumping) |
zoxide query -l | List all directories in database, sorted by score |
zoxide query -l foo | List all matches for “foo” with scores |
zoxide query -ls foo | List matches with scores, sorted by score |
zoxide query -i foo | Interactive selection mode |
Migrating from another directory jumper? Import your database:
| Command | Description |
|---|
zoxide import --from=autojump /path/to/db | Import from autojump |
zoxide import --from=z /path/to/db | Import from z/z.sh |
zoxide import --from=fasd /path/to/db | Import from fasd |
Default database locations to import:
- autojump:
~/.local/share/autojump/autojump.txt
- z:
~/.z
- fasd:
~/.fasd
| Variable | Default | Description |
|---|
_ZO_DATA_DIR | Platform-specific | Directory to store the database |
_ZO_ECHO | 0 | Print matched directory before navigating (1 to enable) |
_ZO_EXCLUDE_DIRS | None | Directories to exclude (colon-separated paths) |
_ZO_FZF_OPTS | None | Custom options passed to fzf in interactive mode |
_ZO_MAXAGE | 10000 | Maximum number of entries in the database |
_ZO_RESOLVE_SYMLINKS | 0 | Resolve symlinks before storing paths (1 to enable) |
| Option | Description |
|---|
--cmd j | Change command name from z to j (creates j and ji) |
--hook prompt | Update scores on every prompt (default) |
--hook pwd | Update scores only when directory changes |
--hook none | Never auto-update scores |
--no-cmd | Don’t create z and zi aliases (use __zoxide_z directly) |
# Example: use 'j' instead of 'z', update on directory change only
eval "$(zoxide init bash --cmd j --hook pwd)"
# Exclude home directory and tmp from tracking
export _ZO_EXCLUDE_DIRS="$HOME:/tmp:/private/tmp"
# Use custom fzf preview
export _ZO_FZF_OPTS="--preview 'eza -la --icons {2..}' --preview-window=right:40%"
# Jump to a project directory by partial name
z myproject
# Disambiguate with multiple keywords
z work api # matches ~/work/projects/api-server
# Interactive mode when you're not sure
zi deploy # opens fzf with all matching directories
# Check what zoxide thinks is the best match
zoxide query deploy
# See all tracked directories and their scores
zoxide query -ls
# Clean up deleted directories from the database
zoxide query -l | while read -r line; do
dir=$(echo "$line" | awk '{print $2}')
[ ! -d "$dir" ] && zoxide remove "$dir"
done
When you use zi, zoxide automatically uses fzf for interactive selection. Make sure fzf is installed for this to work.
zoxide provides tab completions. After shell integration, pressing Tab after z will suggest matching directories.
| Feature | cd | zoxide (z) |
|---|
| Go to exact path | cd /full/path | z /full/path |
| Partial matching | No | Yes (z proj) |
| Frecency ranking | No | Yes |
| Interactive selection | No | Yes (zi) |
| Previous directory | cd - | z - |
| Learning behavior | No | Learns from usage |
| Database import | N/A | autojump, z, fasd |
| Issue | Solution |
|---|
z command not found | Ensure shell integration line is in your shell config and restart shell |
| No matches found | Visit directories with cd first — zoxide learns over time |
| Wrong directory matched | Use more specific keywords: z work api instead of z api |
| Database too large | Lower _ZO_MAXAGE or run zoxide edit to clean up |
