ajeetdsouza/zoxide

^{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

[![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 • Installation • Configuration • Integrations

Getting started

![Tutorial][tutorial]

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)

Read more about the matching algorithm [here][algorithm-matching].

Installation

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][issues].

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

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

   > winget install ajeetdsouza.zoxide
   > 

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

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

   > 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.

   > eval "$(zoxide init bash)"
   > 

   > eval (zoxide init elvish | slurp)
   > 

   > zoxide init fish | source
   > 

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

   > source ~/.zoxide.nu
   > 

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

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

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

   > eval "$(zoxide init zsh)"
   > 

   > 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][fzf-installation].

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

• --no-cmd
• Prevents zoxide from defining the z and zi commands.
• These functions will still be available in your shell as __zoxide_z and

Environment variables

Environment variables[^2] 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:

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

• _ZO_EXCLUDE_DIRS
• Excludes the specified directories from the database.
• This is provided as a list of [globs][glob], separated by OS-specific

| 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

• _ZO_MAXAGE
• Configures the [aging algorithm][algorithm-aging], which limits the maximum

• By default, this is set to 10000.
• _ZO_RESOLVE_SYMLINKS
• When set to 1, z will resolve symlinks before adding directories to the

Third-party integrations

| Application | Description | Plugin | | --------------------- | -------------------------------------------- | --------------------------------------- | | [aerc] | Email client | Natively supported | | [alfred] | macOS launcher | [alfred-zoxide] | | [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][lf-wiki] | | [nnn] | File manager | [nnn-autojump] | | [ranger] | File manager | [ranger-zoxide] | | [raycast] | macOS launcher | [raycast-zoxide] | | [rfm] | File manager | Natively supported | | [sesh] | tmux session manager | Natively supported | | [superfile] | File manager | [Natively supported][superfile-plugins] | | [telescope.nvim] | Fuzzy finder for Neovim | [telescope-zoxide] | | [tmux-session-wizard] | tmux session manager | Natively supported | | [tmux-sessionx] | tmux session manager | Natively supported | | [vim] / [neovim] | Text editor | [zoxide.vim] | | [xplr] | File manager | [zoxide.xplr] | | [xxh] | Transports shell configuration over SSH | [xxh-plugin-prerun-zoxide] | | [yazi] | File manager | Natively supported | | [zabb] | Finds the shortest possible query for a path | Natively supported | | [zesh] | zellij session manager | Natively supported | | [zsh-autocomplete] | Realtime completions for zsh | Natively supported |

[^1]: Debian / Ubuntu derivatives update their packages very slowly. If you're using one of these distributions, consider using the install script instead.

[^2]: If you're not sure how to set an environment variable on your shell, check out the [wiki][wiki-env].

[aerc]: https://github.com/rjarry/aerc [alfred]: https://www.alfredapp.com/ [alfred-zoxide]: https://github.com/yihou/alfred-zoxide [algorithm-aging]: https://github.com/ajeetdsouza/zoxide/wiki/Algorithm#aging [algorithm-matching]: https://github.com/ajeetdsouza/zoxide/wiki/Algorithm#matching [alpine linux packages]: https://pkgs.alpinelinux.org/packages?name=zoxide [arch linux extra]: https://archlinux.org/packages/extra/x86_64/zoxide/ [builtwithnix-badge]: https://img.shields.io/badge/builtwith-nix-7d81f7?logo=nixos&logoColor=white&style=flat-square [builtwithnix]: https://builtwithnix.org/ [chocolatey]: https://community.chocolatey.org/packages/zoxide [clink-zoxide]: https://github.com/shunsambongi/clink-zoxide [clink]: https://github.com/mridgers/clink [conda-forge]: https://anaconda.org/conda-forge/zoxide [crates.io-badge]: https://img.shields.io/crates/v/zoxide?logo=rust&logoColor=white&style=flat-square [crates.io]: https://crates.io/crates/zoxide [debian packages]: https://packages.debian.org/stable/admin/zoxide [exherbo packages]: https://gitlab.exherbo.org/exherbo/rust/-/tree/master/packages/sys-apps/zoxide [devuan packages]: https://pkginfo.devuan.org/cgi-bin/package-query.html?c=package&q=zoxide [downloads-badge]: https://img.shields.io/github/downloads/ajeetdsouza/zoxide/total?logo=github&logoColor=white&style=flat-square [dports]: https://github.com/DragonFlyBSD/DPorts/tree/master/sysutils/zoxide [emacs]: https://www.gnu.org/software/emacs/ [fedora packages]: https://src.fedoraproject.org/rpms/rust-zoxide [felix]: https://github.com/kyoheiu/felix [freshports]: https://www.freshports.org/sysutils/zoxide/ [fzf-installation]: https://github.com/junegunn/fzf#installation [fzf-man]: https://manpages.ubuntu.com/manpages/en/man1/fzf.1.html [fzf]: https://github.com/junegunn/fzf [gentoo packages]: https://packages.gentoo.org/packages/app-shells/zoxide [glob]: https://man7.org/linux/man-pages/man7/glob.7.html [guix]: https://packages.guix.gnu.org/packages/zoxide/ [homebrew]: https://formulae.brew.sh/formula/zoxide [issues]: https://github.com/ajeetdsouza/zoxide/issues/new [joshuto]: https://github.com/kamiyaa/joshuto [lf]: https://github.com/gokcehan/lf [lf-wiki]: https://github.com/gokcehan/lf/wiki/Integrations#zoxide [linuxbrew]: https://formulae.brew.sh/formula-linux/zoxide [macports]: https://ports.macports.org/port/zoxide/summary [neovim]: https://github.com/neovim/neovim [nixpkgs]: https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/zo/zoxide/package.nix [nnn-autojump]: https://github.com/jarun/nnn/blob/master/plugins/autojump [nnn]: https://github.com/jarun/nnn [opensuse factory]: https://build.opensuse.org/package/show/openSUSE:Factory/zoxide [pacstall packages]: https://pacstall.dev/packages/zoxide-deb [pkgsrc]: https://pkgsrc.se/sysutils/zoxide [ranger-zoxide]: https://github.com/jchook/ranger-zoxide [ranger]: https://github.com/ranger/ranger [raspbian packages]: https://archive.raspbian.org/raspbian/pool/main/r/rust-zoxide/ [raycast]: https://www.raycast.com/ [raycast-zoxide]: https://www.raycast.com/mrpunkin/raycast-zoxide [releases]: https://github.com/ajeetdsouza/zoxide/releases [rfm]: https://github.com/dsxmachina/rfm [scoop]: https://github.com/ScoopInstaller/Main/tree/master/bucket/zoxide.json [sesh]: https://github.com/joshmedeski/sesh [slackbuilds]: https://slackbuilds.org/repository/15.0/system/zoxide/ [slackbuilds-howto]: https://slackbuilds.org/howto/ [solus packages]: https://github.com/getsolus/packages/tree/main/packages/z/zoxide/ [superfile]: https://github.com/yorukot/superfile [superfile-plugins]: https://superfile.dev/list/plugin-list/ [telescope-zoxide]: https://github.com/jvgrootveld/telescope-zoxide [telescope.nvim]: https://github.com/nvim-telescope/telescope.nvim [termux]: https://github.com/termux/termux-packages/tree/master/packages/zoxide [tmux-session-wizard]: https://github.com/27medkamal/tmux-session-wizard [tmux-sessionx]: https://github.com/omerxx/tmux-sessionx [tutorial]: contrib/tutorial.gif [ubuntu packages]: https://packages.ubuntu.com/jammy/zoxide [vim]: https://github.com/vim/vim [void linux packages]: https://github.com/void-linux/void-packages/tree/master/srcpkgs/zoxide [warp]: https://www.warp.dev [wiki-env]: https://github.com/ajeetdsouza/zoxide/wiki/HOWTO:-set-environment-variables "HOWTO: set environment variables" [xplr]: https://github.com/sayanarijit/xplr [xxh-plugin-prerun-zoxide]: https://github.com/xxh/xxh-plugin-prerun-zoxide [xxh]: https://github.com/xxh/xxh [yazi]: https://github.com/sxyazi/yazi [zabb]: https://github.com/Mellbourn/zabb [zesh]: https://github.com/roberte777/zesh [zoxide.el]: https://gitlab.com/Vonfry/zoxide.el [zoxide.vim]: https://github.com/nanotee/zoxide.vim [zoxide.xplr]: https://github.com/sayanarijit/zoxide.xplr [zsh-autocomplete]: https://github.com/marlonrichert/zsh-autocomplete