zoxide cheat sheet

replaces cd

Jump to directories by frecency — a cd command that learns your habits.

Covers zoxide 0.9.9. Click any command for details & copy · press / to search.

Jumping (z)

`z foo`	Jump to the highest-frecency directory matching 'foo'
`z foo bar`	Jump to the highest-frecency directory matching both keywords
`z foo/`	Jump to a relative path (works like plain cd for relative paths)
`z ~/foo`	Jump to an absolute path (z works as a drop-in for cd here)
`z foo /`	Jump to a subdirectory of a matched path starting with 'foo'
`z ..`	Go up one directory level (mirrors plain cd behavior)
`z -`	Return to the previous directory (toggle between last two locations)
`z foo<SPACE><TAB>`	Show interactive tab-completions for matching directories (bash 4.4+, fish, zsh only)

Interactive Selection (zi)

`zi`	Open fzf picker over all tracked directories — select one to jump to
`zi foo`	Open fzf picker pre-filtered to directories matching 'foo'
`zoxide query --interactive foo`	Same as zi — invoke interactive selection via the query subcommand directly

Query (inspect database)

`zoxide query foo`	Print the best-matching directory path for 'foo' without jumping
`zoxide query -l foo`	List all matching directories (not just the top result)
`zoxide query -l -s foo`	List all matches with their frecency scores
`zoxide query -l`	List every directory in the database
`zoxide query --all foo`	Include directories that no longer exist on disk in results
`zoxide query --exclude /some/path foo`	Exclude a specific path from query results (useful to skip cwd)
`zoxide query -i foo`	Interactive query with fzf (equivalent to zi foo)
`zoxide query --base-dir /home/user foo`	Restrict results to directories within a given base directory

Add

`zoxide add /path/to/dir`	Manually add a directory to the database (or increment its rank if already present)
`zoxide add /path/to/dir --score 50`	Add a directory with a specific initial/increment score instead of 1
`zoxide add .`	Add the current directory manually to the database

Remove

`zoxide remove /path/to/dir` ⚠	Permanently delete a specific directory path from the database
`zoxide remove -i` ⚠	Interactively select a directory to remove (uses fzf)

Edit (direct database editing)

zoxide edit ⚠ Open the database in your $EDITOR for direct editing — modify or delete entries manually

Import (migrate from z / autojump)

`zoxide import --from z ~/.z`	Import entries from a z (rupa/z) database file
`zoxide import --from autojump ~/.local/share/autojump/autojump.txt`	Import entries from an autojump database file
`zoxide import --from z ~/.z --merge`	Import and merge into the existing zoxide database rather than replacing it

Shell Integration (init)

`eval "$(zoxide init bash)"`	Initialize zoxide for bash — add to ~/.bashrc
`eval "$(zoxide init zsh)"`	Initialize zoxide for zsh — add to ~/.zshrc (after compinit)
`zoxide init fish \| source`	Initialize zoxide for fish — add to ~/.config/fish/config.fish
`zoxide init bash --cmd j`	Initialize with a custom command prefix — creates j and ji instead of z and zi
`zoxide init bash --cmd cd`	Replace the cd command itself with zoxide (not supported on Nushell/POSIX shells)
`zoxide init bash --no-cmd`	Initialize without defining z/zi — functions available as __zoxide_z and __zoxide_zi for custom wrappers
`zoxide init bash --hook prompt`	Score directories at every shell prompt instead of on directory change (default: pwd)
`zoxide init bash --hook none`	Disable automatic scoring; only manual zoxide add calls update the database
`zoxide init posix --hook prompt`	Initialize for any POSIX-compatible shell (requires --hook prompt for POSIX shells)

Environment Variables (config)

`export _ZO_DATA_DIR="$HOME/.local/share/zoxide"`	Override the directory where zoxide stores its database (default varies by OS: ~/.local/share on Linux, ~/Library/Application Support on macOS)
`export _ZO_ECHO=1`	Print the matched directory path to stdout before navigating to it
`export _ZO_EXCLUDE_DIRS="$HOME:$HOME/tmp/*"`	Colon-separated list of glob patterns for directories to never add to the database (semicolon-separated on Windows)
`export _ZO_FZF_OPTS="--height 40% --reverse"`	Pass custom flags to fzf for zi interactive selection
`export _ZO_MAXAGE=10000`	Maximum total frecency score across the database before aging kicks in (default: 10000). Lower values = more aggressive pruning of rarely-visited dirs
`export _ZO_RESOLVE_SYMLINKS=1`	Resolve symlinks to their real paths before storing in the database

Killer recipes

zi with eza tree preview

export _ZO_FZF_OPTS="--preview 'eza --tree --level=2 --color=always {}' --preview-window=right:50%"
zi

Interactive directory picker where the fzf preview pane shows a two-level directory tree via eza — lets you visually confirm what's inside before jumping

Jump and immediately list contents

z proj && eza --long --git --icons

Jump to the best match for 'proj' and immediately show a rich long-listing with git status and icons — the zoxide+eza combo that replaces 'cd && ls -la'

Open file in bat from any matched dir

bat "$(zoxide query proj)/README.md"

Resolve the best-matching directory for a keyword and pipe it into bat to view a file — no need to cd first

ripgrep across a frecency-matched project

rg 'TODO' "$(zoxide query myapp)"

Use zoxide query to resolve a project path and pass it directly to ripgrep — search any tracked project without knowing its full path

Bulk-boost important directories

zoxide add ~/projects/critical --score 200
zoxide add ~/work/client --score 200

Manually set high scores on directories you always want to win — useful when a new project hasn't built up frecency yet but you know it should rank first

Audit and clean stale entries

zoxide query -l -s | awk '{print $2}' | while read d; do [ -d "$d" ] || echo "MISSING: $d"; done

List all tracked directories with scores and flag any that no longer exist on disk — then use zoxide remove to clean them up

Notes & tips

SHELL INIT ORDER For zsh, eval \"$(zoxide init zsh)\" must come AFTER compinit in ~/.zshrc, or tab-completions will not register.

FRECENCY ALGORITHM zoxide uses a frecency score (frequency + recency). Each visit increments a counter by 1. At query time the score is multiplied by a recency factor: 4x if visited within the last hour, 2x within the last day, 0.5x within the last week, 0.25x otherwise. When the total score across all entries exceeds _ZO_MAXAGE, all scores are divided by a factor so the new total is ~90% of the limit, and any entry falling below 1 is dropped.

REQUIRES fzf FOR zi The zi command and -i / --interactive flag require fzf v0.51.0 or later. Without fzf installed, interactive selection will fail with an error.

_ZO_EXCLUDE_DIRS DEFAULT: $HOME is excluded by default. If you want zoxide to track your home directory itself, you must override _ZO_EXCLUDE_DIRS. After changing exclude patterns, use zoxide remove to clean up already-tracked entries that should now be excluded.

DATABASE LOCATION On macOS the database lives in ~/Library/Application Support/zoxide/db.zo. On Linux/BSD: ~/.local/share/zoxide/db.zo. Override with _ZO_DATA_DIR.

--cmd cd GOTCHA: Using --cmd cd to replace cd entirely does not work on Nushell or POSIX shells. On zsh/bash/fish it works well and makes zoxide completely transparent.

--no-cmd USE CASE: Use --no-cmd when you want to define your own wrapper functions around __zoxide_z and __zoxide_zi (e.g., to add logging or extra behavior) without conflicting with zoxide's generated definitions.

IMPORT ONCE zoxide import is a one-shot migration tool. Running it again without --merge will overwrite the database. With --merge it combines scores additively.