zoxide cd Replacement

zoxide cheatsheet — smart cd replacement that learns your habits. z project — jump to most-used match. zi — interactive picker with fzf. Works with bash, zsh, fish, and more.

5 min read

What it is

zoxide is a blazing-fast, intelligent cd command replacement that learns your file navigation habits to make finding and switching directories more efficient.

Installation

Linux:

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

Then, add the following to your shell’s configuration file (e.g., ~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish):

# For bash/zsh
eval "$(zoxide init bash)"
# For fish
zoxide init fish | source

macOS:

Using Homebrew:

brew install zoxide

Then, add the following to your shell’s configuration file (e.g., ~/.zshrc, ~/.bash_profile):

# For zsh
eval "$(zoxide init zsh)"

Windows:

Using Scoop:

scoop install zoxide

Then, add the following to your PowerShell profile:

Invoke-Expression "$(zoxide init pwsh)"

Core Concepts

Fuzzy Matching: zoxide doesn’t require exact directory names. It uses fuzzy matching to find the most relevant directory based on your input and its learned scores.
Scoring: zoxide maintains a database of directories you’ve visited, assigning a score to each based on frequency and recency. This score determines which directory is selected when multiple matches are found.
z command: This is the primary command that replaces cd. You type z followed by a part of the directory name you want to navigate to.
zi command: Similar to z, but it opens the directory in your default file explorer.

Commands / Usage

Navigating Directories

Navigate to a directory using fuzzy matching:
```
z src
```
This will change your current directory to the most relevant directory containing "src" in its path, based on zoxide’s learned scores.
Navigate to a specific subdirectory:
```
z frontend/components
```
If "frontend/components" is a commonly visited path, zoxide will quickly take you there.
Navigate to a directory with multiple matches (interactive selection):
```
z proj
```
If zoxide finds multiple directories like ~/projects/my-project and ~/personal/project-ideas, it will present an interactive list for you to choose from.
Open a directory in your file explorer:
```
zi docs
```
This command will open the most relevant directory matching "docs" in your system’s default file explorer.
Navigate with a specific path prefix:
```
z ~/code/
```
This is useful if you want to constrain the search to directories within ~/code/.

Managing the Database

Add a directory to the database:
```
zi src/utils
```
This command not only navigates but also explicitly adds src/utils to zoxide’s tracking database.
Remove a directory from the database:
```
zi --remove ~/old-project
```
This removes the specified directory from zoxide’s history and scores.
Remove a directory by interactive selection:
```
zi --remove
```
This will present an interactive list of all tracked directories, allowing you to select which ones to remove.
Clean up stale entries (directories that no longer exist):
```
zi --clean
```
This scans your tracked directories and removes any that have been deleted from your filesystem.
Clear the entire database:
```
zi --clear
```
This will reset zoxide’s memory completely, removing all tracked directories and their scores.
Show the database contents:
```
zi --list
```
Displays all directories currently tracked by zoxide, along with their scores.
Show the database contents with scores:
```
zi --list-scores
```
Similar to --list, but also shows the internal score for each directory.

Configuration and Options

Set the number of results to show in interactive mode:
```
zi --interactive-limit 5
```
This limits the interactive selection prompt to a maximum of 5 choices.
Set the "freshness" threshold (how recently a directory was visited to be considered "fresh"):
```
zi --fresh-threshold 10m
```
Directories visited within the last 10 minutes are considered "fresh" and might be prioritized.
Exclude specific directories from tracking:
```
zi --exclude ~/Downloads
```
This prevents zoxide from tracking any entries within the ~/Downloads directory.
Include only specific directories (whitelist):
```
zi --include ~/projects
```
zoxide will only track directories found within ~/projects.
Set the path to the zoxide database file:
```
zi --data-file ~/.zoxide.db
```
This allows you to specify a custom location for zoxide’s database.
Set the number of times to search for a path:
```
zi --num-search-depth 5
```
Controls how many levels deep zoxide will search for a matching directory.

Common Patterns

Quickly switch to a project directory:
```
z myproj
```
This is the most common use case. If you’ve visited ~/projects/my-awesome-project before, this will take you there.
Navigate to a subdirectory within a frequently used project:
```
z myproj/src/components
```
zoxide’s scoring will likely prioritize ~/projects/my-awesome-project as the base, making it easy to reach deeper paths.
Clean up old, unused directories:
```
zi --clean
```
Run this periodically to keep your zoxide database tidy.
Combine with other commands:
```
z myproj && git status
```
Navigate to your project directory and then immediately check its Git status.
Open a directory for editing in your IDE:
```
# Assuming 'code' is your IDE command
z myproj/backend && code .
```
Navigate to your backend directory and open it in VS Code.

Gotchas

Initial learning curve: zoxide needs time to learn your habits. The first few days might feel similar to cd, but its intelligence grows with use.
Conflicting with cd: Ensure your shell configuration correctly loads zoxide init after any default cd aliases or functions that might interfere.
Symlinks: zoxide generally handles symlinks well, resolving them to their target directories. However, in complex nested symlink scenarios, behavior might vary.
Case sensitivity: zoxide’s matching is case-sensitive by default. Use the --case-insensitive flag during initialization if needed, or be mindful of casing in your input.
Database corruption: While rare, if your ~/.zoxide.db file becomes corrupted, you might need to clear it (zi --clear) and let zoxide rebuild its knowledge.
Multiple shells: If you use zoxide in multiple shells simultaneously (e.g., terminal and an IDE’s integrated terminal), ensure each shell’s configuration is updated and that the database file is accessible.