# zoxide [![crates.io][crates.io-badge]][crates.io] [![Downloads][downloads-badge]][releases] [![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

z foo        # cd into highest ranked directory matching foo
z foo bar    # cd into highest ranked directory matching foo and bar

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)

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:

curl -sS https://webinstall.dev/zoxide | bash

Alternatively, 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 | | 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 |

Windows

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

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

Alternatively, 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):

eval "$(zoxide init bash)"

Elvish

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

eval (zoxide init elvish | slurp)

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

Fish

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

zoxide init fish | source

Nushell

Add this to your configuration (find it by running config path in Nushell):

startup = ["zoxide init nushell --hook prompt | save ~/.zoxide.nu", "source ~/.zoxide.nu"]

Note: zoxide only supports Nushell v0.37.0 and above.

PowerShell

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

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):

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

Zsh

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

eval "$(zoxide init zsh)"

Any POSIX shell

Add this to your configuration:

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.

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

zoxide import --from autojump path/to/db

z, z.lua, or zsh-z

zoxide import --from z path/to/db

Configuration

Flags

When calling zoxide init, the following flags are available:

  • --cmd
  • Changes the prefix of predefined aliases (z, zi).
  • --cmd j would change the aliases 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-aliases
  • Don't define aliases (z, zi).
  • 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 | {FOLDERID_RoamingAppData} | C:\Users\Alice\AppData\Roaming |
  • _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 | | ------------------ | --------------------------------------- | -------------------------- | | emacs | Text editor | zoxide.el | | 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 | | zsh-autocomplete | Realtime completions for zsh | Supported by default |

Repo Not Found