34 releases
0.9.6 | Sep 19, 2024 |
---|---|
0.9.4 | Feb 20, 2024 |
0.9.2 | Aug 4, 2023 |
0.9.1 | May 7, 2023 |
0.3.0 | Mar 30, 2020 |
#5 in Command line utilities
2,794 downloads per month
1MB
3K
SLoC
Special thanks to:
zoxide
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
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 (zoxide v0.8.0+, bash 4.4+/fish/zsh only)
Read more about the matching algorithm here.
Installation
zoxide can be installed in 4 easy steps:
-
Install binary
zoxide runs on most major platforms. If your platform isn't listed below, please open an issue.
Linux / WSL
The recommended way to install zoxide is via the install script:
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 asdf asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git
asdf install zoxide latest
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
CentOS 7+ Copr dnf copr enable atim/zoxide
dnf install zoxide
Debian 11+[^1]Debian Packagesapt install zoxide
Devuan 4.0+ Devuan Packages apt install zoxide
Exherbo Linux Exherbo packages cave resolve -x repository/rust
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 11+[^1]Raspbian Packagesapt install zoxide
Rhino Linux Pacstall Packages pacstall -I zoxide-deb
Slackware 15.0+ SlackBuilds Instructions Solus Solus Packages eopkg install zoxide
Ubuntu 21.04+[^1]Ubuntu Packagesapt 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
Homebrew brew install zoxide
asdf asdf plugin add zoxide https://github.com/nyrst/asdf-zoxide.git
asdf install zoxide latest
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:
curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh
Windows
zoxide works with PowerShell, as well as shells running in Cygwin, Git Bash, and MSYS2.
The recommended way to install zoxide is via
winget
: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:
curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh
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
Or, run this command in your terminal:
curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash
Android
To install zoxide, use a package manager:
Repository Instructions Termux pkg install zoxide
Or, run this command in your terminal:
curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash
-
Setup zoxide on your shell
To start using zoxide, add it to your shell.
Bash
Add this to the end of your config file (usually
~/.bashrc
):eval "$(zoxide init bash)"
Elvish
Add this to the end of your config file (usually
~/.elvish/rc.elv
):eval (zoxide init elvish | slurp)
Note zoxide only supports elvish v0.18.0 and above.
Fish
Add this to the end of your config file (usually
~/.config/fish/config.fish
):zoxide init fish | source
Ksh
Add this to the end of your config file (usually
~/.kshrc
):# ksh93 eval "$(zoxide init ksh)" # mksh, oksh, etc. eval "$(zoxide init ksh --hook=prompt)"
Nushell
Add this to the end of your env file (find it by running
$nu.env-path
in Nushell):zoxide init nushell | save -f ~/.zoxide.nu
Now, add this to the end of your config file (find it by running
$nu.config-path
in Nushell):source ~/.zoxide.nu
Note zoxide only supports Nushell v0.89.0+.
PowerShell
Add this to the end of your config file (find it by running
echo $profile
in PowerShell):Invoke-Expression (& { (zoxide init powershell | Out-String) })
Xonsh
Add this to the end of your config file (usually
~/.xonshrc
):execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide')
Zsh
Add this to the end of your config file (usually
~/.zshrc
):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 runningrm ~/.zcompdump*; compinit
.Any POSIX shell
Add this to the end of your config file:
eval "$(zoxide init posix --hook prompt)"
-
Install fzf (optional)
fzf is a command-line fuzzy finder, used by zoxide for completions / interactive selection. It can be installed from here.
Note zoxide only supports fzf v0.33.0 and above.
-
Import your data (optional)
If you currently use any of these plugins, you may want to import your data into zoxide:
autojump
Run this command in your terminal:
zoxide import --from=autojump "/path/to/autojump/db"
The path usually 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
fasd, z, z.lua, zsh-z
Run this command in your terminal:
zoxide import --from=z "path/to/z/db"
The path usually varies according to your system:
Plugin Path fasd $_FASD_DATA
or$HOME/.fasd
z (bash/zsh) $_Z_DATA
or$HOME/.z
z (fish) $Z_DATA
or$XDG_DATA_HOME/z/data
or$HOME/.local/share/z/data
z.lua (bash/zsh) $_ZL_DATA
or$HOME/.zlua
z.lua (fish) $XDG_DATA_HOME/zlua/zlua.txt
or$HOME/.local/share/zlua/zlua.txt
or$_ZL_DATA
zsh-z $ZSHZ_DATA
or$_Z_DATA
or$HOME/.z
ZLocation
Run this command in 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
andzi
commands. --cmd j
would change the commands to (j
,ji
).--cmd cd
would replace thecd
command.
- Changes the prefix of the
--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
- Changes how often zoxide increments a directory's score:
--no-cmd
- Prevents zoxide from defining the
z
andzi
commands. - These functions will still be available in your shell as
__zoxide_z
and__zoxide_zi
, should you choose to redefine them.
- Prevents zoxide from defining the
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
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.
- When set to 1,
_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
_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.
- When set to 1,
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 |
nnn | File manager | nnn-autojump |
ranger | File manager | ranger-zoxide |
telescope.nvim | Fuzzy finder for Neovim | telescope-zoxide |
t | tmux session manager |
Natively supported |
tmux-session-wizard | 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 |
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.
Dependencies
~5–18MB
~219K SLoC