zoxide

A smarter cd command. Supports all major shells.

21,562

526

21,562

100

View on GitHub

Top Related Projects

fzf

63,665

:cherry_blossom: A command-line fuzzy finder

fd

33,285

A simple, fast and user-friendly alternative to 'find'

ripgrep

47,483

ripgrep recursively searches directories for a regex pattern while respecting your gitignore

navi

14,818

An interactive cheatsheet tool for the command-line

fasd

5,894

Command-line productivity booster, offers quick access to files and directories, inspired by autojump, z and v.

Quick Overview

Zoxide is a smarter cd command for your terminal, designed to help you navigate your filesystem more efficiently. It learns your habits and allows you to jump to frequently used directories without typing the full path.

Pros

Fast and efficient navigation through directories
Learns from your usage patterns automatically
Cross-platform support (Linux, macOS, Windows)
Written in Rust, offering excellent performance

Cons

Requires initial setup and integration with your shell
May take some time to build up an effective database of frequently used directories
Could potentially conflict with existing aliases or functions named 'z'
Might be overkill for users who don't frequently navigate complex directory structures

Code Examples

# Jump to a directory that contains 'Downloads'
z Downloads

# Jump to a directory that contains both 'projects' and 'rust'
z projects rust

# List the top 10 directories matched by a query
z -l rust

Getting Started

Install zoxide:

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

Add the following to your shell configuration file (e.g., .bashrc, .zshrc):
```
eval "$(zoxide init bash)"  # or zsh, fish, etc.
```
Restart your shell or source the configuration file:
```
source ~/.bashrc  # or ~/.zshrc, etc.
```
Start using zoxide by navigating to directories with the z command.

Competitor Comparisons

fzf

63,665

:cherry_blossom: A command-line fuzzy finder

Pros of fzf

More versatile, can be used for general-purpose fuzzy finding beyond just directory navigation
Highly customizable with extensive options and keybindings
Integrates well with various command-line tools and text editors

Cons of fzf

Requires more setup and configuration to achieve similar directory navigation functionality as zoxide
Can be slower for large datasets compared to zoxide's algorithmic approach
Steeper learning curve for advanced features and customizations

Code Comparison

zoxide:

z foo       # cd to highest ranked directory matching foo
zi foo      # cd with interactive selection
zq foo bar  # cd to highest ranked directory matching foo and bar

fzf:

cd $(find . -type d | fzf)

Key Differences

zoxide focuses specifically on smart directory navigation, while fzf is a general-purpose fuzzy finder
zoxide uses a ranking algorithm to prioritize frequently and recently accessed directories, whereas fzf relies on fuzzy matching of input strings
fzf provides a more interactive and visual selection process, while zoxide offers a simpler command-line interface for quick navigation

Both tools can significantly improve command-line productivity, with zoxide excelling in directory navigation and fzf offering broader fuzzy finding capabilities across various use cases.

fd

33,285

A simple, fast and user-friendly alternative to 'find'

Pros of fd

Faster and more user-friendly alternative to the find command
Colorized output and smart case sensitivity by default
Extensive command-line options for fine-tuned searches

Cons of fd

Limited to file and directory searches
Doesn't learn from user behavior or provide smart navigation
Requires manual input of search patterns each time

Code Comparison

fd:

fd -e txt
fd '^x.*rc$'
fd -H -I --changed-within 1d

zoxide:

z documents
zi doc
zoxide query -l

Key Differences

fd is a file search tool, while zoxide is a smarter cd command that learns from your navigation habits. fd excels at quickly finding files and directories based on patterns, while zoxide focuses on improving directory navigation by learning from your most frequently and recently accessed paths.

fd is more suitable for one-time searches or when you need to find specific files, while zoxide shines in everyday directory navigation, especially in large project structures or complex directory hierarchies.

While both tools aim to improve command-line productivity, they serve different purposes and can be used complementarily in a developer's workflow.

ripgrep

47,483

ripgrep recursively searches directories for a regex pattern while respecting your gitignore

Pros of ripgrep

Extremely fast and efficient for searching large codebases
Supports various file types and encoding formats
Highly customizable with numerous command-line options

Cons of ripgrep

Limited to text search functionality
Steeper learning curve for advanced features
Requires manual navigation to search results

Code comparison

ripgrep:

rg "pattern" /path/to/search

zoxide:

z directory_name

Summary

While ripgrep excels in fast text searching across large codebases, zoxide focuses on intelligent directory navigation. ripgrep offers powerful search capabilities with support for various file types and encoding formats, making it ideal for developers working with complex projects. However, it's limited to text search functionality and requires manual navigation to search results.

zoxide, on the other hand, provides a simpler, more intuitive approach to directory navigation. It learns from your usage patterns and allows quick jumping to frequently accessed directories. This can significantly improve workflow efficiency, especially for users who frequently switch between projects or deep directory structures.

The choice between these tools depends on the specific needs of the user. Developers who frequently search through large codebases may prefer ripgrep, while those looking to optimize their directory navigation might find zoxide more beneficial. Many users may find value in using both tools in conjunction to enhance their overall productivity.

navi

14,818

An interactive cheatsheet tool for the command-line

Pros of navi

Offers an interactive cheatsheet for command-line tools and workflows
Supports multiple programming languages and shell environments
Allows for easy sharing and customization of cheatsheets

Cons of navi

Requires manual creation and maintenance of cheatsheets
May have a steeper learning curve for new users
Focuses on command lookup rather than directory navigation

Code Comparison

navi:

navi --query "git commit"
navi --cheatsheet ~/.local/share/navi/cheats/custom.cheat

zoxide:

z documents
zi  # interactive selection
zoxide add /path/to/directory

Key Differences

Purpose: navi is a command cheatsheet tool, while zoxide is a smarter cd command for faster directory navigation
Functionality: navi helps users remember and discover commands, zoxide learns from usage patterns to improve navigation
User interaction: navi offers an interactive interface for browsing commands, zoxide provides quick directory jumping

Use Cases

navi is ideal for:

Learning new command-line tools
Managing complex workflows
Sharing knowledge within teams

zoxide excels at:

Quickly navigating between frequently used directories
Improving productivity for users who work across many projects
Simplifying command-line navigation without manual configuration

z

16,285

z - jump around

Pros of z

Lightweight and simple implementation in shell script
Extensive compatibility with various shells (bash, zsh, fish)
Long-standing project with a large user base and community support

Cons of z

Slower performance compared to Zoxide, especially with large directories
Less actively maintained, with fewer recent updates
Limited advanced features and customization options

Code Comparison

_z() {
  local datafile="${_Z_DATA:-$HOME/.z}"
  # ... (implementation details)
}

Zoxide:

pub fn query(keywords: &[String], all: bool) -> Result<Vec<ScoredPath>> {
    let db = db::init()?;
    let matches = db.query(keywords, all);
    Ok(matches)
}

Key Differences

z is written in shell script, while Zoxide is implemented in Rust
Zoxide offers better performance and more advanced features
z has broader shell compatibility out-of-the-box
Zoxide provides a more modern and actively maintained codebase
z relies on simpler data storage, while Zoxide uses a more sophisticated database approach

Both tools serve similar purposes for directory navigation, but Zoxide offers improved performance and features at the cost of a slightly more complex setup.

fasd

5,894

Command-line productivity booster, offers quick access to files and directories, inspired by autojump, z and v.

Pros of fasd

Written in shell script, making it more portable and easier to modify
Supports a wider range of shells (bash, zsh, fish, ksh)
Offers more customization options and flexibility

Cons of fasd

Slower performance, especially on larger directories
Less actively maintained (last update in 2015)
Requires more manual configuration to achieve optimal results

Code Comparison

fasd:

_fasd_preexec() {
  { eval "fasd --proc $(fasd --sanitize $1)"; } >> "/dev/null" 2>&1
}

zoxide:

pub fn add(path: &Path) -> Result<()> {
    let mut db = db::init()?;
    db.increment(path)?;
    db.save()
}

Key Differences

Language: fasd is written in shell script, while zoxide is written in Rust
Performance: zoxide generally offers better performance, especially for larger directories
Maintenance: zoxide is more actively maintained and updated
Ease of use: zoxide provides a simpler out-of-the-box experience with less configuration required
Functionality: Both offer similar core functionality, but fasd provides more customization options

Overall, zoxide is a more modern and performant alternative to fasd, while fasd offers more flexibility and customization for users willing to invest time in configuration.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

^{Special thanks to:}

Warp is a modern, Rust-based terminal with AI built in so you and your team can build great software, faster.

^{Visit warp.dev to learn more.}

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

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<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+~~¹ ~~Debian Packages~~ ~~apt 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~~¹ ~~apt install zoxide~~
~~Raspbian 11+~~¹ ~~Raspbian Packages~~ ~~apt install zoxide~~
Rhino Linux Pacstall Packages pacstall -I zoxide-deb
Slackware 15.0+ SlackBuilds Instructions
Solus Solus Packages eopkg install zoxide
~~Ubuntu 21.04+~~¹ ~~Ubuntu Packages~~ ~~apt install zoxide~~
Void Linux Void Linux Packages xbps-install -S zoxide

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+~~¹	~~Debian Packages~~	~~`apt 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~~¹		~~`apt install zoxide`~~
~~Raspbian 11+~~¹	~~Raspbian Packages~~	~~`apt install zoxide`~~
Rhino Linux	Pacstall Packages	`pacstall -I zoxide-deb`
Slackware 15.0+	SlackBuilds	Instructions
Solus	Solus Packages	`eopkg 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
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

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`

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

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

Or, run this command in your terminal:
curl -sS https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | bash

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

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
```
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 running rm ~/.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.

Repository	Instructions
Termux	`pkg install zoxide`

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

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

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

Hook	Description
`none`	Never
`prompt`	At every shell prompt
`pwd`	Whenever the directory is changed

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	`%LOCALAPPDATA%`	`C:\Users\Alice\AppData\Local`

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

OS	Separator	Example
Linux / macOS / BSD	`:`	`$HOME:$HOME/private/*`
Windows	`;`	`$HOME;$HOME/private/*`

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

Debian / Ubuntu derivatives update their packages very slowly. If you're using one of these distributions, consider using the install script instead. ↩ ↩² ↩³ ↩⁴
If you're not sure how to set an environment variable on your shell, check out the wiki. ↩

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Code Examples

Getting Started

Competitor Comparisons

Pros of fzf

Cons of fzf

Code Comparison

Key Differences

Pros of fd

Cons of fd

Code Comparison

Key Differences

Pros of ripgrep

Cons of ripgrep

Code comparison

Summary

Pros of navi

Cons of navi

Code Comparison

Key Differences

Use Cases

Pros of z

Cons of z

Code Comparison

Key Differences

Pros of fasd

Cons of fasd

Code Comparison

Key Differences

Convert designs to code with AI

README

zoxide

Getting started

Installation

Configuration

Flags

Environment variables

Third-party integrations

Footnotes

Top Related Projects

Convert designs to code with AI