zoxide is a smarter cd command designed to enhance directory navigation by remembering frequently accessed directories. It allows users to "jump" to these directories with minimal keystrokes, significantly improving workflow efficiency.
Key Features:
Smart Directory Remembering: Tracks and prioritizes directories based on usage frequency.
Cross-Shell Compatibility: Works seamlessly across all major shells, including Bash, Fish, Zsh, PowerShell, and more.
Fuzzy Matching: Enables quick navigation to directories with partial matches or patterns.
Interactive Selection with fzf (Optional): Provides an interactive interface for selecting directories using the popular fuzzy finder tool.
Tab Completions: Supports intelligent tab completions for enhanced usability.
Audience & Benefit:
Ideal for developers, system administrators, and anyone working in terminal environments who need to navigate complex directory structures. By reducing the time spent on repetitive navigation tasks, zoxide enhances productivity and streamlines workflows.
zoxide can be installed via winget on Windows, making it accessible across multiple platforms.
README
Special thanks to:
<a href="https://go.warp.dev/zoxide"><img alt="Sponsored by Warp" width="230" src="https://raw.githubusercontent.com/warpdotdev/brand-assets/refs/heads/main/Github/Sponsor/Warp-Github-LG-03.png" /></a>
<div><b>Warp, built for coding with multiple AI agents.</b></div>
<div>Available for macOS, Linux, and Windows.</div>
<div>
Visit
<a href="https://go.warp.dev/zoxide">warp.dev</a>
to learn more.
</div>
<a href="https://www.recall.ai/careers?ashby_jid=7b02811e-bc91-4ef2-925d-f56a5acac13b&utm_source=github&utm_medium=sponsorship&utm_campaign=zoxide"><img alt="Sponsored by Recall.ai" width="230" src="https://github.com/user-attachments/assets/0c5cb177-561c-4637-bef6-cf584939c829" /></a>
<div>Processing over 3TB/s of video at peak load,</div>
<div>now <a href="https://www.recall.ai/careers?ashby_jid=7b02811e-bc91-4ef2-925d-f56a5acac13b&utm_source=github&utm_medium=sponsorship&utm_campaign=zoxide">hiring in SF.</a></div>
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.
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)
z foo # show interactive completions (bash 4.4+/fish/zsh only)
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:
>
> sh > 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 | 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/rustcave 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 |
> | 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:
>
> sh > 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:
>
> sh > 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:
>
> sh > 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:
>
> sh > 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:
>
> sh > curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash >
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):
>
> sh > eval "$(zoxide init bash)" >
Elvish
> Add this to the end of your config file (usually ~/.elvish/rc.elv):
>
> sh > 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):
>
> sh > zoxide init fish | source >
Nushell
> Add this to the end of your env file (find it by running $nu.env-path
> in Nushell):
>
> sh > 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):
>
> sh > source ~/.zoxide.nu >
>
> Note:
> zoxide only supports Nushell v0.106.0+.
PowerShell
> Add this to the end of your config file (find it by running
> echo $profile in PowerShell):
>
> powershell > Invoke-Expression (& { (zoxide init powershell | Out-String) }) >
Tcsh
> Add this to the end of your config file (usually ~/.tcshrc):
>
> sh > zoxide init tcsh > ~/.zoxide.tcsh > source ~/.zoxide.tcsh >
Xonsh
> Add this to the end of your config file (usually ~/.xonshrc):
>
> python > execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide') >
Zsh
> Add this to the end of your config file (usually ~/.zshrc):
>
> sh > eval "$(zoxide init zsh)" >
>
> For completions to work, the above line must be added aftercompinit 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:
>
> sh > eval "$(zoxide init posix --hook prompt)" >
> Note:
> Warp provides its own completions, so Space+Tab completions are not
> supported there.
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.
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
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
Configuration
Flags
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
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
Environment variables2 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/zoxide or $HOME/.local/share/zoxide
/home/alice/.local/share/zoxide
macOS
$HOME/Library/Application Support/zoxide
/Users/Alice/Library/Application Support/zoxide
Windows
%LOCALAPPDATA%\zoxide
C:\Users\Alice\AppData\Local\zoxide
_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.
Debian / Ubuntu derivatives update their packages very slowly. If you're
using one of these distributions, consider using the install script instead. ↩↩2↩3↩4
If you're not sure how to set an environment variable on your shell, check
out the wiki. ↩
