^{Special thanks to:}

Warp, built for coding with multiple AI agents. Available for macOS, Linux, and Windows. Visit warp.dev to learn more.

Processing over 3TB/s of video at peak load, now hiring in SF.

---

zoxide

zoxide is a smarter cd command, inspired by z and autojump.

It remembers which directories you use most frequently, so you can "jump" to them in just a few keystrokes.
zoxide works on all major shells.

Getting started • Installation • Configuration • Integrations

z foo              # cd into highest ranked directory matching foo
z foo bar          # cd into highest ranked directory matching foo and bar
z foo /            # cd into a subdirectory starting with foo

z ~/foo            # z also works like a regular cd command
z foo/             # cd into relative path
z ..               # cd one level up
z -                # cd into previous directory

zi foo             # cd with interactive selection (using fzf)

zoxide feedback foo --path ~/the/intended/directory
                   # teach zoxide that a directory is the intended result

z foo<SPACE><TAB>  # show interactive completions (bash 4.4+/fish/zsh only)

Read more about the matching algorithm here.

zoxide query, z, and zi use the unified fuzzy-rank::path::fuzzy adaptor and one globally comparable result type. Exact basename-component matches are strong enough to stop further work. If exact candidates only have a weaker ancestor, component, or substring signal, zoxide also evaluates typo candidates and merges the two sets. This prevents a weak exact ancestor from hiding a better basename typo. _ZO_TYPO_FALLBACK=0 disables that additional typo pass without disabling exact matching. zi evaluates every path through the same unified matcher because its purpose is to display all selectable results.

The fuzzy-rank comparator uses this fifteen-stage ordering:

1. [PATH.EXACT_BASENAME_COMPONENT] Exact whole query-token phrase in the basename component.
2. [PATH.EXACT_COMPONENT] Exact whole query-token phrase in any component.
3. [CORE.EXACT_PHRASE_PRESENT] Exact whole-query phrase presence within one path component.
4. [CORE.EXACT_SUBPHRASE_COUNTS_VECTOR] Exact proper contiguous query-token subphrase-presence vector, descending and lexicographic.
5. [CORE.EXACT_COVERAGE] Exact distinct query-token coverage, descending.
6. [PATH.ORDERED_COMPOUND_COVERAGE] Ordered query coverage reconstructed across path-token boundaries.
7. [CORE.ALIGNMENT_COST_VECTOR] Alignment and fragmentation cost, worst alignment first.
8. [CORE.ORDER_VIOLATION_DISTANCE] Query-to-candidate token assignment inversion count, ascending.
9. [PATH.SEGMENT_VECTOR] Segment-count vector, preferring the basename and then nearer ancestors.
10. [CORE.POSITION_VECTOR_SIMPLE] Whole-or-prefix/suffix/middle count vector, descending and lexicographic.
11. [CORE.SCORE_DESC] Caller-provided frecency score, descending.
12. [CORE.TYPO_COST_VECTOR] Per-query-token weighted core typo costs, worst cost first.
13. [CORE.INSERTION_VECTOR] Per-query-token candidate-side insertion counts, worst count first.
14. [PATH.DEPTH] Path depth, ascending.
15. [CORE.KEY_ASC] Path string, ascending.

Each bracketed name identifies the fuzzy-rank code implementing that stage. TypoMatch.exact is retained as result provenance for the exact fallback and ambiguity policy; it is not an additional sort key. Repeated names in other adaptors mean the implementation is genuinely shared.

These are strict lexicographic pipelines, not independently weighted scores. Each stage partitions only candidates tied at every preceding stage; a later key cannot compensate for a worse earlier key. Comparison code accesses subordinate keys only when the preceding keys compare equal. Non-interactive matching skips the entire typo alignment stage when the exact partition is non-empty. Metrics emitted together by one required typo alignment are retained rather than recomputing that alignment once per key.

The path-specific keys mean:

• segment is 0 for the basename, 1 for its parent, 2 for the next parent, and so on. Multi-token matches average their matched segment values.
• position is 0 at the start of a matched segment token, 1 at its end, and 2 in its middle. Multi-token matches sum their position values.
• insertions is candidate-side text not covered by the selected match.
• c is the shared weighted typo cost. Exact matches always display c=0.
• Exact phrase runs use token-prefix exactness and never cross a path separator.
• Exact distinct coverage can collect query tokens from different path components.

First-result queries scan eligible database entries through this staged ordering, retain only a bounded top-result shortlist, and check filesystem existence while building that shortlist when required. Interactive and list modes use the same comparator. Weak exact and typo candidates are merged for non-interactive selection when no exact basename candidate exists.

zoxide records successful single-result and interactive selections in preferences.zo beside db.zo. The file is bounded and independent of the directory database. A query-to-directory preference is considered after the hard exact-basename rule and before the generic comparator, so repeated choices can resolve ambiguities without allowing a remembered preference to defeat a direct exact basename match.

Use zoxide feedback <keywords...> --path <directory> when a query selected the wrong directory. This records an explicit correction without requiring a second interactive search. When the intended directory was among the matched candidates, the same command also performs a bounded pairwise update to a compact linear path model stored in preferences.zo. The model is inactive until explicit feedback supplies a preference signal, so ordinary queries keep the existing lazy comparator cost. Preference lookup and model inference are in-process and perform no additional filesystem work.

Interactive zi / cdi rows are displayed as:

<frecency> c=<core cost> s=<segment> p=<position> i=<insertions> <path>

Interactive queries do not preflight every database path with filesystem metadata before opening the picker. This prevents a cold HDD containing an old directory entry from delaying the initial results. The selected path is validated after selection unless --all was requested. Non-interactive queries filter stale entries while building their bounded exact and typo candidate sets, so a cold drive can still be touched when those paths are eligible for a non-interactive result.

• s, p, and i expose the path-specific ranking inputs.
• The display order does not change the comparator hierarchy above.
• Exact rows show c=0; typo rows show their weighted core cost.

zoxide can be installed in 4 easy steps:

1. Install binary

   zoxide runs on most major platforms. If your platform isn't listed below, please open an issue.

   Linux / WSL

   The recommended way to install zoxide is via the install script:

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

   Or, you can use a package manager:

   Distribution	Repository	Instructions
   Any	crates.io	cargo install zoxide --locked
   Any	asdf	asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git asdf install zoxide latest
   Any	conda-forge	conda install -c conda-forge zoxide
   Any	guix	guix install zoxide
   Any	Linuxbrew	brew install zoxide
   Any	nixpkgs	nix-env -iA nixpkgs.zoxide
   Alpine Linux 3.13+	Alpine Linux Packages	apk add zoxide
   Arch Linux	Arch Linux Extra	pacman -S zoxide
   Debian1	Debian Packages	apt install zoxide
   Devuan 4.0+	Devuan Packages	apt install zoxide
   Exherbo Linux	Exherbo packages	cave resolve -x repository/rust cave resolve -x zoxide
   Fedora 32+	Fedora Packages	dnf install zoxide
   Gentoo	Gentoo Packages	emerge app-shells/zoxide
   Manjaro		pacman -S zoxide
   openSUSE Tumbleweed	openSUSE Factory	zypper install zoxide
   Parrot OS1		apt install zoxide
   Raspbian1	Raspbian Packages	apt install zoxide
   Rhino Linux	Pacstall Packages	pacstall -I zoxide-deb
   Slackware 15.0+	SlackBuilds	Instructions
   Solus	Solus Packages	eopkg install zoxide
   Ubuntu1	Ubuntu Packages	apt install zoxide
   Void Linux	Void Linux Packages	xbps-install -S zoxide

   macOS

   To install zoxide, use a package manager:

   Repository	Instructions
   crates.io	cargo install zoxide --locked
   Homebrew	brew install zoxide
   asdf	asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git asdf install zoxide latest
   conda-forge	conda install -c conda-forge zoxide
   MacPorts	port install zoxide
   nixpkgs	nix-env -iA nixpkgs.zoxide

   Or, run this command in your terminal:

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

   Windows

   zoxide works with PowerShell, as well as shells running in Cygwin, Git Bash, and MSYS2.

   The recommended way to install zoxide is via winget:

   winget install ajeetdsouza.zoxide

   Or, you can use an alternative package manager:

   Repository	Instructions
   crates.io	cargo install zoxide --locked
   Chocolatey	choco install zoxide
   conda-forge	conda install -c conda-forge zoxide
   Scoop	scoop install zoxide

   If you're using Cygwin, Git Bash, or MSYS2, you can also use the install script:

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

   BSD

   To install zoxide, use a package manager:

   Distribution	Repository	Instructions
   Any	crates.io	cargo install zoxide --locked
   DragonFly BSD	DPorts	pkg install zoxide
   FreeBSD	FreshPorts	pkg install zoxide
   NetBSD	pkgsrc	pkgin install zoxide

   Or, run this command in your terminal:

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

   Android

   To install zoxide, use a package manager:

   Repository	Instructions
   Termux	pkg install zoxide

   Or, run this command in your terminal:

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

2. Setup zoxide on your shell

   To start using zoxide, add it to your shell.

   Bash

   Add this to the end of your config file (usually ~/.bashrc):

   eval "$(zoxide init bash)"

   Elvish

   Add this to the end of your config file (usually ~/.elvish/rc.elv):

   eval (zoxide init elvish | slurp)

   Note: zoxide only supports elvish v0.18.0 and above.

   Fish

   Add this to the end of your config file (usually ~/.config/fish/config.fish):

   zoxide init fish | source

   Nushell

   Add this to the end of your env file (find it by running $nu.env-path in Nushell):

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

   Now, add this to the end of your config file (find it by running $nu.config-path in Nushell):

   source ~/.zoxide.nu

   Note: zoxide only supports Nushell v0.89.0+.

   PowerShell

   Add this to the end of your config file (find it by running echo $profile in PowerShell):

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

   Tcsh

   Add this to the end of your config file (usually ~/.tcshrc):

   zoxide init tcsh > ~/.zoxide.tcsh
   source ~/.zoxide.tcsh

   Xonsh

   Add this to the end of your config file (usually ~/.xonshrc):

   execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')

   Zsh

   Add this to the end of your config file (usually ~/.zshrc):

   eval "$(zoxide init zsh)"

   For completions to work, the above line must be added after compinit is called. You may have to rebuild your completions cache by running rm ~/.zcompdump*; compinit.

   Any POSIX shell

   Add this to the end of your config file:

   eval "$(zoxide init posix --hook prompt)"

   Note: Warp provides its own completions, so Space+Tab completions are not supported there.

3. Install fzf ^(optional)

   fzf is a command-line fuzzy finder, used by zoxide for completions / interactive selection. It can be installed from here.

   Note: The minimum supported fzf version is v0.51.0.

4. Import your data ^(optional)

   If you currently use any of these plugins, you may want to import your data into zoxide. The data file is auto-detected using each plugin's standard conventions.

   zoxide import <plugin>

   Plugin	Command
   atuin	zoxide import atuin
   autojump	zoxide import autojump
   fasd	zoxide import fasd
   z	zoxide import z
   z.lua	zoxide import z.lua
   zsh-z	zoxide import zsh-z

When calling zoxide init, the following flags are available:

• --cmd

  • Changes the prefix of the z and zi commands.
  • --cmd j would change the commands to (j, ji).
  • --cmd cd would replace the cd command.

• --hook <HOOK>

  • Changes how often zoxide increments a directory's score:

    Hook	Description
    none	Never
    prompt	At every shell prompt
    pwd (default)	Whenever the directory is changed

• --no-cmd

  • Prevents zoxide from defining the z and zi commands.
  • These functions will still be available in your shell as __zoxide_z and __zoxide_zi, should you choose to redefine them.

Environment variables² can be used for configuration. They must be set before zoxide init is called.

• _ZO_DATA_DIR

  • Specifies the directory in which the database is stored.

  • The default value varies across OSes:

    OS	Path	Example
    Linux / BSD	$XDG_DATA_HOME or $HOME/.local/share	/home/alice/.local/share
    macOS	$HOME/Library/Application Support	/Users/Alice/Library/Application Support
    Windows	%LOCALAPPDATA%	C:\Users\Alice\AppData\Local

• _ZO_ECHO

  • When set to 1, z will print the matched directory before navigating to it.

• _ZO_EXCLUDE_DIRS

  • Excludes the specified directories from the database.

  • This is provided as a list of globs, separated by OS-specific characters:

    OS	Separator	Example
    Linux / macOS / BSD	:	$HOME:$HOME/private/*
    Windows	;	$HOME;$HOME/private/*

  • By default, this is set to "$HOME".

• _ZO_FZF_OPTS

  • Custom options to pass to fzf during interactive selection. See man fzf for the list of options.

• _ZO_MAXAGE

  • Configures the aging algorithm, which limits the maximum number of entries in the database.
  • By default, this is set to 10000.

• _ZO_RESOLVE_SYMLINKS

  • When set to 1, z will resolve symlinks before adding directories to the database.