Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install zd

It will make the zd command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall zd uninstalls.

Back to the crate overview.

Readme

zd

Fast recursive directory jumper. Type a name, land in the folder.

No database. No learning phase. No config files. Single binary, works instantly.

~/Projects $ z api
~/Projects/backend/src/api $

Install

cargo install zd

Or build from source:

git clone https://github.com/antoinehoriot/zd.git
cd zd
cargo install --path .

Setup

Add the shell wrapper to your profile so z can cd for you:

bash / zsh — add to ~/.bashrc or ~/.zshrc:

eval "$(zd --init bash)"

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

zd --init fish | source

This creates a tiny z() function that calls zd and cds into the result.

Usage

z api          # jump to best match for "api"
z models src   # search for "models" starting from ./src

How matching works

zd scans directories recursively from your current directory (or a given root) and scores each path:

Match type	Score
Exact basename	100
Basename starts with	70
Basename contains	40
Full path segment	20

Deeper directories get a small penalty so shallower matches rank higher. The top 50 results are shown.

Interactive picker

When multiple directories match, an inline picker appears:

zd > api_
> ~/Projects/backend/src/api
  ~/Projects/frontend/src/api
  ~/Projects/docs/api-reference

↑/k ↓/j — navigate
Type to filter live
Enter — confirm
Esc — cancel

Flags

zd <QUERY> [ROOT]

Options:
  -1, --best             Print single best match (no picker)
  -a, --all              Print all matches, one per line
  -d, --max-depth <N>    Max recursion depth [default: 8]
      --no-skip          Don't skip node_modules, .git, target, etc.
      --init <SHELL>     Print shell init script (bash|zsh|fish)
  -h, --help             Print help
  -V, --version          Print version

Scripting

# Jump to the best match non-interactively
cd "$(zd -1 config)"

# List all matching directories
zd -a test | head -5

Skipped directories

By default zd skips directories like node_modules, target, .git, venv, build, .docker, and ~30 others to keep results fast and relevant. Pass --no-skip to include everything.

Performance

zd uses parallel directory walking (via the ignore crate) and respects .gitignore rules. Scanning 100k directories typically completes in under 200ms.

License

MIT