ajeetdsouza · Trending

ajeetdsouza/zoxide

A smarter cd command. Supports all major shells.

View on GitHub Website / Demo Back to listing

40.1kstars 923forks 100+contributors Rust

README.md

<sup>Special thanks to:</sup>

<table>
  <tr>
    <td align="center">
      
      <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><sup><b>Warp, built for coding with multiple AI agents.</b></sup></div>
      <div><sup>Available for macOS, Linux, and Windows.</sup></div>
      <div><sup>
        Visit
        <a href="https://go.warp.dev/zoxide"><u>warp.dev</u></a>
        to learn more.
      </sup></div>
    </td>
    <td align="center">
      
      <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><sup>Processing over 3TB/s of video at peak load,</sup></div>
      
      <div><sup>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></sup></div>
    </td>
  </tr>
</table>

<hr />

<h1>
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./contrib/logo-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="./contrib/logo-light.svg">
    <img alt="zoxide logo" src="./contrib/logo-light.svg" height="128" width="128">
  </picture>
  <br />
  zoxide
</h1>

[![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.<br />
zoxide works on all major shells.

[Getting started](#getting-started) •
[Installation](#installation) •
[Configuration](#configuration) •
[Integrations](#third-party-integrations)

</div>

## Getting started

![Tutorial][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<SPACE><TAB>  # 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].

<details>
   <summary>Linux / WSL</summary>

> 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`                                                |
   > | ~~Debian~~[^1]      | ~~[Debian Packages]~~   | ~~`apt install zoxide`~~                                          |
   > | Devuan 4.0+         | [Devuan Packages]       | `apt install zoxide`                                              |
   > | Exherbo Linux       | [Exherbo packages]      | `cave resolve -x repository/rust` <br /> `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 OS~~[^1]   |                         | ~~`apt install zoxide`~~                                          |
   > | ~~Raspbian~~[^1]    | ~~[Raspbian Packages]~~ | ~~`apt install zoxide`~~                                          |
   > | Rhino Linux         | [Pacstall Packages]     | `pacstall -I zoxide-deb`                                          |
   > | Slackware 15.0+     | [SlackBuilds]           | [Instructions][slackbuilds-howto]                                 |
   > | Solus               | [Solus Packages]        | `eopkg install zoxide`                                            |
   > | ~~Ubuntu~~[^1]      | ~~[Ubuntu Packages]~~   | ~~`apt install zoxide`~~                                          |
   > | Void Linux          | [Void Linux Packages]   | `xbps-install -S zoxide`                                          |

</details>

<details>
   <summary>macOS</summary>

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

</details>

<details>
   <summary>Windows</summary>

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

</details>

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

</details>

<details>
   <summary>Android</summary>

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

</details>

2. **Setup zoxide on your shell**

To start using zoxide, add it to your shell.

> Add this to the <ins>**end**</ins> of your config file (usually `~/.bashrc`):
   >
   > ```sh
   > eval "$(zoxide init bash)"
   > ```

</details>

<details>
   <summary>Elvish</summary>

> Add this to the <ins>**end**</ins> of your config file (usually `~/.elvish/rc.elv`):
   >
   > ```sh
   > eval (zoxide init elvish | slurp)
   > ```
   >
   > **Note:**
   > zoxide only supports elvish v0.18.0 and above.

</details>

> Add this to the <ins>**end**</ins> of your config file (usually
   > `~/.config/fish/config.fish`):
   >
   > ```sh
   > zoxide init fish | source
   > ```

</details>

<details>
   <summary>Nushell</summary>

> Add this to the <ins>**end**</ins> 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 <ins>**end**</ins> 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+.

</details>

<details>
   <summary>PowerShell</summary>

> Add this to the <ins>**end**</ins> of your config file (find it by running
   > `echo $profile` in PowerShell):
   >
   > ```powershell
   > Invoke-Expression (& { (zoxide init powershell | Out-String) })
   > ```

</details>

> Add this to the <ins>**end**</ins> of your config file (usually `~/.tcshrc`):
   >
   > ```sh
   > zoxide init tcsh > ~/.zoxide.tcsh
   > source ~/.zoxide.tcsh
   > ```

</details>

<details>
   <summary>Xonsh</summary>

> Add this to the <ins>**end**</ins> of your config file (usually `~/.xonshrc`):
   >
   > ```python
   > execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')
   > ```

</details>

> Add this to the <ins>**end**</ins> of your config file (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 completions cache by running
   > `rm ~/.zcompdump*; compinit`.

</details>

<details>
   <summary>Any POSIX shell</summary>

> Add this to the <ins>**end**</ins> of your config file:
   >
   > ```sh
   > eval "$(zoxide init posix --hook prompt)"
   > ```

</details>

> **Note:**
   > [Warp] provides its own completions, so `Space+Tab` completions are not
   > supported there.

3. **Install fzf** <sup>(optional)</sup>

[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** <sup>(optional)</sup>

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.

```sh
   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`    |

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

| 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][glob], 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`][fzf-man] for the list of options.
- `_ZO_MAXAGE`
  - Configures the [aging algorithm][algorithm-aging], 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                                  |
| --------------------- | -------------------------------------------- | --------------------------------------- |
| [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

Repository info

Default branch: main
Latest version: v0.10.0
Created: 2020-03-05
Last activity: 2026-10-14
License: MIT
Open issues: 149
Watchers: 81

Contributors

ajeetdsouza

454 contributions

dependabot[bot]

53 contributions

cole-h

9 contributions

alin23

7 contributions

sitiom

5 contributions