# zoxide [![crates.io][crates.io-badge]][crates.io] [![Downloads][downloads-badge]][releases] [![License][license-badge]][license] [![Built with Nix][builtwithnix-badge]][builtwithnix] 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](#getting-started) • [Installation](#installation) • [Configuration](#configuration) • [Integrations](#third-party-integrations)

Getting started

Tutorial

```sh 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 (zoxide v0.8.0+, bash 4.4+/fish/zsh only) ```

Read more about the matching algorithm here.

Installation

Step 1: Install zoxide

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

Linux

To install zoxide, run this command in your terminal:

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

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 | [Linuxbrew] | brew install zoxide | | Alpine Linux 3.13+ | [Alpine Linux Packages] | apk add zoxide | | Arch Linux | [Arch Linux Community] | pacman -S zoxide | | CentOS 7+ | [Copr] | dnf copr enable atim/zoxide
dnf install zoxide | | Debian 11+ | [Debian Packages] | apt install zoxide | | Devuan 4.0+ | [Devuan Packages] | apt install zoxide | | Fedora 32+ | [Fedora Packages] | dnf install zoxide | | Gentoo | [GURU Overlay] | eselect repository enable guru
emerge --sync guru
emerge app-shells/zoxide | | Manjaro | | pacman -S zoxide | | NixOS | [nixpkgs] | nix-env -iA nixpkgs.zoxide | | openSUSE Tumbleweed | [openSUSE Factory] | zypper install zoxide | | Parrot OS | | apt install zoxide | | Raspbian 11+ | [Raspbian Packages] | apt install zoxide | | Ubuntu 21.04+ | [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 | | [conda-forge] | conda install -c conda-forge zoxide | | [Homebrew] | brew install zoxide | | [MacPorts] | port install zoxide |

Or, run this command in your terminal:

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

Windows

To install zoxide, run this command in your command prompt:

sh curl.exe -A "MS" https://webinstall.dev/zoxide | powershell

Or, you can use a 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 |

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 |

Android

To install zoxide, use a package manager:

| Repository | Instructions | | ---------- | -------------------- | | [Termux] | pkg install zoxide |

Step 2: Add zoxide to your shell

To start using zoxide, add it to your shell.

Bash

Add this to your configuration (usually ~/.bashrc):

sh eval "$(zoxide init bash)"

Elvish

Add this to your configuration (usually ~/.elvish/rc.elv):

sh eval (zoxide init elvish | slurp)

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

Fish

Add this to your configuration (usually ~/.config/fish/config.fish):

fish zoxide init fish | source

Note: zoxide only supports fish v3.4.0 and above.

Nushell

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

sh zoxide init nushell | save ~/.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.63.0 and above.

PowerShell

Add this to your configuration (find it by running echo $profile in PowerShell):

```powershell

For zoxide v0.8.0+

Invoke-Expression (& { $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' } (zoxide init --hook $hook powershell | Out-String) })

For older versions of zoxide

Invoke-Expression (& { $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' } (zoxide init --hook $hook powershell) -join "`n" }) ```

Xonsh

Add this to your configuration (usually ~/.xonshrc):

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

Zsh

Add this to your configuration (usually ~/.zshrc):

sh eval "$(zoxide init zsh)"

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

Any POSIX shell

Add this to your configuration:

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

Step 3: Install fzf (optional)

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

Note: zoxide only supports fzf v0.21.0 and above.

Step 4: Import your data (optional)

If you currently use any of the following utilities, you may want to import your data into zoxide:

autojump

sh zoxide import --from autojump path/to/db

The default path varies according to your system:

| OS | Path | Example | | ------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------ | | Linux | $XDG_DATA_HOME/autojump/autojump.txt or $HOME/.local/share/autojump/autojump.txt | /home/alice/.local/share/autojump/autojump.txt | | macOS | $HOME/Library/autojump/autojump.txt | /Users/Alice/Library/autojump/autojump.txt | | Windows | %APPDATA%\autojump\autojump.txt | C:\Users\Alice\AppData\Roaming\autojump\autojump.txt |

z, z.lua, or zsh-z

sh zoxide import --from z path/to/db

ZLocation

powershell $db = New-TemporaryFile (Get-ZLocation).GetEnumerator() | ForEach-Object { Write-Output ($_.Name+'|'+$_.Value+'|0') } | Out-File $db zoxide import --from z $db

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 (doesn't work on Nushell / POSIX shells).
--hook <HOOK>
- Changes how often zoxide increments a directory's score: | Hook | Description | | -------- | --------------------------------- | | none | Never | | prompt | At every shell prompt | | pwd | 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 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.

Third-party integrations

| Application | Description | Plugin | | ------------------ | -------------------------------------------- | -------------------------- | | [clink] | Improved cmd.exe for Windows | [clink-zoxide] | | [emacs] | Text editor | [zoxide.el] | | [felix] | File manager | Natively supported | | [joshuto] | File manager | Natively supported | | [lf] | File manager | See the wiki | | [nnn] | File manager | [nnn-autojump] | | [ranger] | File manager | [ranger-zoxide] | | [telescope.nvim] | Fuzzy finder for Neovim | [telescope-zoxide] | | [vim] | Text editor | [zoxide.vim] | | [xplr] | File manager | [zoxide.xplr] | | [xxh] | Transports shell configuration over SSH | [xxh-plugin-prerun-zoxide] | | [zabb] | Finds the shortest possible query for a path | Natively supported | | [zsh-autocomplete] | Realtime completions for zsh | Natively supported |