1# zoxide 2 3[](https://crates.io/crates/zoxide) 4 5 6A faster way to navigate your filesystem 7 8## Introduction 9 10`zoxide` is a blazing fast alternative to `cd`, inspired by 11[`z`](https://github.com/rupa/z) and [`z.lua`](https://github.com/skywind3000/z.lua). 12It keeps track of the directories you use most frequently, and uses a ranking algorithm 13to navigate to the best match. 14 15 16 17## Examples 18 19```sh 20z foo # cd to highest ranked directory matching foo 21z foo bar # cd to highest ranked directory matching foo and bar 22 23z foo/ # can also cd into actual directories 24 25zi foo # cd with interactive selection using fzf 26``` 27 28## Getting started 29 30### Step 1: Install zoxide 31 32zoxide works across all major platforms. If your distribution isn't included in the list below, you can directly install the binary from GitHub: 33 34```sh 35curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/ajeetdsouza/zoxide/master/install.sh | sh 36``` 37 38If you would rather not run a script, you can download the binary from the [Releases](https://github.com/ajeetdsouza/zoxide/releases) page and add it anywhere in your `$PATH`. 39 40#### On Linux 41 42| Distribution | Repository | Instructions | 43| -------------- | ----------------------- | --------------------------------------------------------- | 44| **Any** | [crates.io] | `cargo install zoxide` | 45| **Any** | [Linuxbrew] | `brew install zoxide` | 46| Alpine Linux | [Alpine Linux Packages] | `apk add zoxide` | 47| Arch Linux | [AUR] | `yay -Sy zoxide-bin` | 48| CentOS | [Copr] | `dnf copr enable atim/zoxide` <br /> `dnf install zoxide` | 49| Debian Testing | [Debian Packages] | `apt install zoxide` | 50| Fedora | [Fedora Packages] | `dnf install zoxide` | 51| NixOS | [nixpkgs] | `nix-env -iA nixpkgs.zoxide` | 52| Parrot OS | | `apt install zoxide` | 53| Void Linux | [Void Linux Packages] | `xbps-install -S zoxide` | 54 55#### On macOS 56 57| Repository | Instructions | 58| ----------- | ---------------------- | 59| [crates.io] | `cargo install zoxide` | 60| [Homebrew] | `brew install zoxide` | 61| [MacPorts] | `port install zoxide` | 62 63#### On Windows 64 65| Repository | Instructions | 66| ----------- | ---------------------- | 67| [crates.io] | `cargo install zoxide` | 68| [Scoop] | `scoop install zoxide` | 69 70#### On BSD 71 72| Distribution | Repository | Instructions | 73| ------------- | ------------ | ---------------------- | 74| **Any** | [crates.io] | `cargo install zoxide` | 75| DragonFly BSD | [DPorts] | `pkg install zoxide` | 76| FreeBSD | [FreshPorts] | `pkg install zoxide` | 77| NetBSD | [pkgsrc] | `pkgin install zoxide` | 78 79#### On Android 80 81| Repository | Instructions | 82| ---------- | -------------------- | 83| [Termux] | `pkg install zoxide` | 84 85### Step 2: Install fzf (optional) 86 87[fzf](https://github.com/junegunn/fzf) is a command-line fuzzy finder, used by 88zoxide for interactive selection. Installation instructions can be found 89[here](https://github.com/junegunn/fzf#installation). 90 91### Step 3: Add zoxide to your shell 92 93If you currently use `z`, `z.lua`, or `zsh-z`, you may want to first import 94your existing entries into `zoxide`: 95 96```sh 97zoxide import --from z /path/to/db 98``` 99 100Alternatively, for `autojump`: 101 102```sh 103zoxide import --from autojump /path/to/db 104``` 105 106#### bash 107 108Add the following line to your configuration file (usually `~/.bashrc`): 109 110```sh 111eval "$(zoxide init bash)" 112``` 113 114#### elvish 115 116Add the following line to your configuration file (usually `~/.elvish/rc.elv`): 117 118```sh 119eval $(zoxide init elvish | slurp) 120``` 121 122#### fish 123 124Add the following line to your configuration file (usually `~/.config/fish/config.fish`): 125 126```fish 127zoxide init fish | source 128``` 129 130#### nushell 131 132Initialize zoxide's Nushell script: 133 134```sh 135zoxide init nushell --hook prompt | save ~/.zoxide.nu 136``` 137 138Then, in your Nushell configuration file: 139 140- Prepend `__zoxide_hook;` to the `prompt` variable. 141- Add the following lines to the `startup` variable: 142 - `zoxide init nushell --hook prompt | save ~/.zoxide.nu` 143 - `source ~/.zoxide.nu` 144 145#### powershell 146 147Add the following line to your profile: 148 149```powershell 150Invoke-Expression (& { 151 $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' } 152 (zoxide init --hook $hook powershell) -join "`n" 153}) 154``` 155 156#### xonsh 157 158Add the following line to your configuration file (usually `~/.xonshrc`): 159 160```python 161execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide') 162``` 163 164#### zsh 165 166Add the following line to your configuration file (usually `~/.zshrc`): 167 168```sh 169eval "$(zoxide init zsh)" 170``` 171 172#### Any POSIX shell 173 174Add the following line to your configuration file: 175 176```sh 177eval "$(zoxide init posix --hook prompt)" 178``` 179 180## Configuration 181 182### `init` flags 183 184- `--cmd`: changes the prefix of predefined aliases (`z`, `zi`). 185 - e.g. `--cmd j` would change the aliases to `j` and `ji` respectively. 186- `--hook <HOOK>`: change how often zoxide increments a directory's score: 187 - `none`: never automatically add directories to zoxide. 188 - `prompt`: add the current directory to zoxide at every shell prompt. 189 - `pwd`: whenever the user changes directories, add the new directory to zoxide. 190- `--no-aliases`: don't define extra aliases (`z`, `zi`). 191 - These functions will still be available in your shell as `__zoxide_z` and `__zoxide_zi`, should you choose to use them elsewhere. 192 193### Environment variables 194 195Be sure to set these before calling `zoxide init`. 196 197- `_ZO_DATA_DIR` 198 - Specifies the directory in which zoxide should store its database. 199 - The default value varies across OSes: 200 | OS | Path | Example | 201 | ----------- | ---------------------------------------- | ------------------------------------------ | 202 | Linux / BSD | `$XDG_DATA_HOME` or `$HOME/.local/share` | `/home/alice/.local/share` | 203 | macOS | `$HOME/Library/Application Support` | `/Users/Alice/Library/Application Support` | 204 | Windows | `{FOLDERID_RoamingAppData}` | `C:\Users\Alice\AppData\Roaming` | 205- `_ZO_ECHO` 206 - When set to `1`, `z` will print the matched directory before navigating to it. 207- `_ZO_EXCLUDE_DIRS` 208 - Excludes the specified directories from the database. 209 - This is provided as a list of [Unix globs](https://man7.org/linux/man-pages/man7/glob.7.html), separated by OS-specific characters: 210 | OS | Separator | Example | 211 | ------------------- | --------- | ----------------------- | 212 | Linux / macOS / BSD | `:` | `$HOME:$HOME/private/*` | 213 | Windows | `;` | `$HOME;$HOME/private/*` | 214- `_ZO_FZF_OPTS` 215 - Custom options to pass to [fzf](https://github.com/junegunn/fzf). See `man fzf` for the list of options. 216- `_ZO_MAXAGE` 217 - Configures the [aging algorithm](https://github.com/ajeetdsouza/zoxide/wiki/Algorithm#aging), which limits the maximum number of entries in the database. 218 - By default, this is set to `10000`. 219- `_ZO_RESOLVE_SYMLINKS` 220 - When set to `1`, `z` will resolve symlinks before adding directories to the database. 221 222## Third-party integrations 223 224- [xxh](https://github.com/xxh/xxh), via [xxh-plugin-prerun-zoxide](https://github.com/xxh/xxh-plugin-prerun-zoxide) 225- [nnn](https://github.com/jarun/nnn), via [autojump plugin](https://github.com/jarun/nnn/blob/master/plugins/autojump) 226 227[alpine linux packages]: https://pkgs.alpinelinux.org/packages?name=zoxide 228[aur]: https://aur.archlinux.org/packages/zoxide-bin 229[copr]: https://copr.fedorainfracloud.org/coprs/atim/zoxide/ 230[crates.io]: https://crates.io/crates/zoxide 231[debian packages]: https://packages.debian.org/testing/admin/zoxide 232[dports]: https://github.com/DragonFlyBSD/DPorts/tree/master/sysutils/zoxide 233[freshports]: https://www.freshports.org/sysutils/zoxide/ 234[fedora packages]: https://src.fedoraproject.org/rpms/rust-zoxide 235[homebrew]: https://formulae.brew.sh/formula/zoxide 236[linuxbrew]: https://formulae.brew.sh/formula-linux/zoxide 237[macports]: https://ports.macports.org/port/zoxide/summary 238[nixpkgs]: https://nixos.org/nixos/packages.html?attr=zoxide&channel=nixpkgs-unstable 239[pkgsrc]: https://pkgsrc.se/sysutils/zoxide 240[scoop]: https://github.com/ScoopInstaller/Main/tree/master/bucket/zoxide.json 241[termux]: https://github.com/termux/termux-packages/tree/master/packages/zoxide 242[void linux packages]: https://github.com/void-linux/void-packages/tree/master/srcpkgs/zoxide 243[`dirs` documentation]: https://docs.rs/dirs/latest/dirs/fn.data_local_dir.html 244
){kind=link}
