A smarter cd command for your terminal

Overview

zoxide

A smarter cd command for your terminal

crates.io

zoxide is a blazing fast replacement for your cd command, inspired by z and z.lua. It keeps track of the directories you use most frequently, and uses a ranking algorithm to navigate to the best match.

Demo

Examples

z foo        # cd into highest ranked directory matching foo
z foo bar    # cd into highest ranked directory matching foo and bar

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)

Read more about the matching algorithm here.

Getting started

Step 1: Install zoxide

zoxide works across all major platforms. If your distribution isn't included in the list below, you can download the binary from the Releases page and copy it to your $PATH.

On Linux

Distribution Repository Instructions
Any crates.io cargo install zoxide
Any Linuxbrew brew install zoxide
Alpine Linux 3.13+ Alpine Linux Packages apk add zoxide
Arch Linux AUR yay -Sy zoxide-bin
CentOS 7+ Copr dnf copr enable atim/zoxide
dnf install zoxide
Debian Testing Debian Packages apt install zoxide
Devuan 4.0+ Devuan Packages apt install zoxide
Fedora 32+ Fedora Packages dnf install zoxide
NixOS nixpkgs nix-env -iA nixpkgs.zoxide
Parrot OS apt install zoxide
Ubuntu 21.04+ Ubuntu Packages apt install zoxide
Void Linux Void Linux Packages xbps-install -S zoxide

On macOS

Repository Instructions
crates.io cargo install zoxide
Homebrew brew install zoxide
MacPorts port install zoxide

On Windows

Repository Instructions
crates.io cargo install zoxide
Scoop scoop install zoxide

On BSD

Distribution Repository Instructions
Any crates.io cargo install zoxide
DragonFly BSD DPorts pkg install zoxide
FreeBSD FreshPorts pkg install zoxide
NetBSD pkgsrc pkgin install zoxide

On Android

Repository Instructions
Termux pkg install zoxide

Step 2: Install fzf (optional)

fzf is a command-line fuzzy finder, used by zoxide for interactive selection. Installation instructions can be found here.

Step 3: Add zoxide to your shell

If you currently use z, z.lua, or zsh-z, you may want to first import your existing entries into zoxide:

zoxide import --from z path/to/db

Alternatively, for autojump (note that scores are not imported):

zoxide import --from autojump path/to/db

bash

Add this to your configuration (usually ~/.bashrc):

eval "$(zoxide init bash)"

elvish

Add this to your configuration (usually ~/.elvish/rc.elv):

eval $(zoxide init elvish | slurp)

fish

Add this to your configuration (usually ~/.config/fish/config.fish):

zoxide init fish | source

nushell

Initialize zoxide's Nushell script:

zoxide init nushell --hook prompt | save ~/.zoxide.nu

Add this to your configuration (usually ~/.config/nu/config.toml):

prompt = "__zoxide_hook;__zoxide_prompt"
startup = ["zoxide init nushell --hook prompt | save ~/.zoxide.nu", "source ~/.zoxide.nu"]

You can replace __zoxide_prompt with a custom prompt.

powershell

Add this to your configuration (the location is stored in $profile):

Invoke-Expression (& {
    $hook = if ($PSVersionTable.PSVersion.Major -lt 6) { 'prompt' } else { 'pwd' }
    (zoxide init --hook $hook powershell) -join "`n"
})

xonsh

Add this to your configuration (usually ~/.xonshrc):

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

zsh

Add this to your configuration (usually ~/.zshrc):

eval "$(zoxide init zsh)"

Any POSIX shell

Add this to your configuration:

eval "$(zoxide init posix --hook prompt)"

Configuration

init flags

  • --cmd: changes the prefix of predefined aliases (z, zi).
    • e.g. --cmd j would change the aliases to j and ji respectively.
  • --hook <HOOK>: change how often zoxide increments a directory's score:
    • none: never automatically add directories to zoxide.
    • prompt: add the current directory to zoxide at every shell prompt.
    • pwd: whenever the user changes directories, add the new directory to zoxide.
  • --no-aliases: don't define extra aliases (z, zi).
    • These functions will still be available in your shell as __zoxide_z and __zoxide_zi, should you choose to use them elsewhere.

Environment variables

Be sure to set these before calling zoxide init.

  • _ZO_DATA_DIR
    • Specifies the directory in which zoxide should store its database.
    • 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 {FOLDERID_RoamingAppData} C:\Users\Alice\AppData\Roaming
  • _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. 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.

Third-party integrations

Issues
  • Support Nu Shell

    Support Nu Shell

    I'd love to be able to use zoxide from Nu Shell.

    opened by andrewbanchich 51
  • Add _ZO_RESOLVE_SYMLINKS to resolve or not symlinks

    Add _ZO_RESOLVE_SYMLINKS to resolve or not symlinks

    Linked to #80.

    _ZO_FOLLOW_SYMLINKS=0 disables the symlinks resolution, making a symlink and its target 2 different entries in the database.

    Example:

    • /tmp/foo-target is a directory
    • /tmp/foo symlinks to /tmp/foo-target

    With _ZO_FOLLOW_SYMLINKS=1 (default behavior), z add /tmp/foo adds /tmp/foo-target in the database.

    With _ZO_FOLLOW_SYMLINKS=0, z add /tmp/foo adds /tmp/foo in the database.

    opened by aruhier 20
  • Import the entries from .z

    Import the entries from .z

    I started using zoxide and am very impressed by its speed compared to other utilities. Am currently using zsh-z. It would be nice if there was a way to import the entries from the earlier $HOME/.z to zoxide database. Any plans on using the existing data?

    opened by alaymari 17
  • could not create database c:\path\to\zoxide\db.zo: access is denied

    could not create database c:\path\to\zoxide\db.zo: access is denied

    nushell is failing tests with the error in the title. any ideas what's going on? i assume that it's running tests in parallel and trying to exclusively lock the db.zo file and getting denied, but i'm not sure.

    opened by fdncred 16
  • Add fish integration

    Add fish integration

    This is a very useful tool! Thanks for creating it and making it open source!

    I added support for the fish shell in case anyone is interested.

    opened by alin23 15
  • [FR] Add `zoxide query --list-fast`

    [FR] Add `zoxide query --list-fast`

    I use my own "frontend" to jump between dirs, and I just zoixide's functionality of remembering directories I have been to. The problem is that zoxide query --list is not optimized to be fast; It seems to process the whole db and check whether dirs exist or not etc. I want a zoxide query --list-fast that just lists all the dirs, sorted by their score, as fast as possible.

    opened by NightMachinary 14
  • Detailed comparison of different hook options

    Detailed comparison of different hook options

    Sorry to annoy you with such simple issues. But the documentation is not too extensive and I did not look into the code myself so far. So while setting up zoxide on my PC (coming from fasd), I wonder which hook option I should choose during initialization. Let's disregard none option. For me it looks like the pwd option has the advantage that it does not run so often (depending on the user behavior) and therefore consumes less time (in total). So what is the point of prompt? What I could imagine is that the score of the current working directory increases with each command I run inside. This means the more I'm working inside a specific directory the more "important" it gets. Not sure it that is the case, but this could have a variety of advantages as I could imagine (e.g. git worktrees). Thanks for your help in advance.

    PS: Does it make sense to cache the initialization? That was recommended for fasd and I wonder if this is beneficial here as well to safe shell startup time.

    opened by weilbith 13
  • zoxide v0.3

    zoxide v0.3

    Closes https://github.com/ajeetdsouza/zoxide/issues/45, closes https://github.com/ajeetdsouza/zoxide/issues/44, closes https://github.com/ajeetdsouza/zoxide/issues/42, closes https://github.com/ajeetdsouza/zoxide/issues/39, closes https://github.com/ajeetdsouza/zoxide/issues/16, closes https://github.com/ajeetdsouza/zoxide/issues/7.

    opened by ajeetdsouza 12
  • Add POSIX shell support

    Add POSIX shell support

    Any users of a shell that adheres to the POSIX standard should now be supported. Shells that were tested while this feature was in development include mrsh, dash, busybox ash, and bash --posix.

    The hooks work by defining a _zoxide_hook function and adding it to the shell's PS1 (causing it to be evaluated every time the prompt is redrawn).

    The PWD hook uses a hack to get it to work properly. Variables are not available outside of the functions defining them (even if exported), so we write the current PWD to a temporary file, /tmp/.zo_pwd. This is not ideal, but I cannot think of a better solution apart from removing the hook entirely.


    Fix #42

    opened by cole-h 10
  • fuzzy match for typoes

    fuzzy match for typoes

    Hi, I'm coming from using autojump after being recommended this from a coworker. I love the blazing speed of zoxide.

    Below are some examples for fuzzy matching.

    Screen Shot 2020-03-14 at 15 43 13

    ( Note: you can see the echo that's mentioned in https://github.com/ajeetdsouza/zoxide/issues/22 )

    I also miss jo (open matching directory. for mac this is something like open (zoxide query $argv) )

    opened by danielb2 10
  • Smart case search

    Smart case search

    Hello, vim has very handy option smartcase to do case-sensitive search if there is any capital letter in search query, otherwise search is case-insensitive. I have directory called V, and if I type z V I am moved, e.g. into ~/.config/nvim directory. I have to use longer z parent/V to give z a hint. Therefore, I think it makes sense for z to support notion of smart case as well, it would make tool more comfortable to use.

    opened by fenuks 0
  • Support for cmd.exe

    Support for cmd.exe

    Usually I use cmder as a shell which mostly wraps cmd in Windows -- and I'm really happy with it -- i.e.: https://cmder.net/ (https://github.com/cmderdev/cmder).

    Is it possible to use zoxide in it? I only found instructions for power shell in windows, not really cmd, but maybe I missed something...

    opened by fabioz 2
  • Improve Fish's completions

    Improve Fish's completions

    This PR brings two improvements to Fish's completions, when completing {{cmd}}:

    • Let Fish only complete directories and excludes files

    • If there is no match in the current directory, Fish will query zoxide with current token and serve them as completions:

      image

      This is approximately the same as using zoxide query -i <current token>, but more integrated with Fish.

    Let me know if you have any suggestion over these two changes.

    opened by kidonng 4
  • WIP: new syntax in nushell

    WIP: new syntax in nushell

    Hey @ajeetdsouza , Just dropping by to let you know that we're working on changing some of the syntax in nushell. The two PRs below contain some breaking changes. We just released build 0.31.0 yesterday (5/11/2021). With build 0.31.0 your existing integration code still works. These new breaking changes start in build 0.31.1.

    Simplify expressions Simplify string interpolation

    What I had to do to get the .zoxide.nu script working this morning, after building from main, was to replace all $( with (. After I did that it worked just fine. We plan on releasing these changes in 0.32 approximately 3 weeks from now.

    We're still experimenting so things may change in the next 3 weeks. If you don't mind, I'll try to keep updating here if there are further breaking changes that affect zoxide. Feel free to come hang with us on Discord while we figure work on our latest changes.

    opened by fdncred 1
  • One-liner install instruction doesn't work

    One-liner install instruction doesn't work

    I am trying to install zoxide with the one-liner on a Raspberry Pi 4 running Raspberry Pi OS, but the script gets stuck here when trying to install Rust:

    ❯ curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/ajeetdsouza/zoxide/master/install.sh | sh
    No binaries are available for your CPU architecture (armv7l)
    Compiling from source...
    Cargo will be installed.
    

    However separately downloading the script and running it works fine:

    ❯ curl https://raw.githubusercontent.com/ajeetdsouza/zoxide/master/install.sh --output install.sh
    ❯ chmod +x install.sh
    ❯ ./install.sh
    Compiling from source...
    Cargo will be installed.
    Is this okay? (y/N): y
    info: downloading installerr
    
    Welcome to Rust!
    ...
    

    Obviously this is not a huge issue since in the end I was able to install zoxide, but it would be nice if the given instructions worked here too (and to know what is different between the two methods).

    opened by kolmone 1
  • Support UNC Paths on windows

    Support UNC Paths on windows

    Currently zoxide outputs an when navigating to UNC paths like SMB shares \\NAS\Share or WSL files \\wsl$\fedoraremix:

    zoxide: invalid path: UNC(
        "wsl$",
        "fedoraremix",
    ) \\wsl$\fedoraremix
    
    
    opened by davidkna 2
  • Feature: Most recently accessed path - like z.lua offers

    Feature: Most recently accessed path - like z.lua offers

    Hi, thanks for Zoxide! The only feature I miss is z.lua's "Most Recently Accessed Path" showcased here: https://github.com/skywind3000/z.lua#most-recently-accessed-path

    It's a really convenient way of drilling outwards and can combined with file-managers.

    opened by rafi 1
  • Case insensitivity

    Case insensitivity

    Hi. My filesystem is case-insensitive but case-preserving, and I've noticed that I have both foo and Foo in my zoxide database. Is there some way to tell zoxide that these are the same directory and should be counted together? Thanks!

    opened by christianbundy 4
  • Feature request: tcsh support

    Feature request: tcsh support

    The tcsh does not seem to be supported. I’d like to see support for it.

    opened by dertuxmalwieder 5
  • Publish benchmark among other popular navigators

    Publish benchmark among other popular navigators

    Hi there, I am a new user of your tool. It serves my purpose very well so I appreciate the effort that you are putting into it.

    I do acknowledge that this is your repo and it is your interest to create something to the world. As an end user, I still couldn't help but wonder how it performs next to tools like z.lua, z, etc. and what is its advantages beside being written in Rust. Therefore, I would love it if you share some benchmarks.

    Again, this is totally optional and not really an issue. Just some good motivations that I think would be beneficial to the users of this and the developers who investigate it to contribute more to the development.

    opened by luong-komorebi 4
Releases(v0.7.0)
Owner
Ajeet D'Souza
Ajeet D'Souza
Linux Kernel Manager and Activity Monitor 🐧💻

Linux Kernel Manager and Activity Monitor ?? ?? The kernel is the part of the operating system that facilitates interactions between hardware and soft

Orhun Parmaksız 1.2k Jun 1, 2021
cloc counts blank lines, comment lines, and physical lines of source code in many programming languages.

cloc Count Lines of Code cloc counts blank lines, comment lines, and physical lines of source code in many programming languages. Latest release: v1.9

null 11.7k Jun 7, 2021
:mag: Google from the terminal

googler is a power tool to Google (web, news, videos and site search) from the command-line. It shows the title, URL and abstract for each result, whi

Piña Colada 5.2k Jun 6, 2021
:speech_balloon: Command-line translator using Google Translate, Bing Translator, Yandex.Translate, etc.

Translate Shell Translate Shell (formerly Google Translate CLI) is a command-line translator powered by Google Translate (default), Bing Translator, Y

Mort Yao 5k Jun 6, 2021
Terminal-based CPU stress and monitoring utility

The Stress Terminal UI: s-tui Stress-Terminal UI, s-tui, monitors CPU temperature, frequency, power and utilization in a graphical way from the termin

Alex Manuskin 2.6k Jun 3, 2021
Magnificent app which corrects your previous console command.

The Fuck The Fuck is a magnificent app, inspired by a @liamosaur tweet, that corrects errors in previous console commands. Is The Fuck too slow? Try t

Vladimir Iakovlev 62.3k Jun 5, 2021
Browse Reddit from your terminal

THIS PROJECT IS NO LONGER MAINTAINED RTV Development is Shutting Down List of Alternative Projects Reddit Terminal Viewer (RTV) A text-based interface

Michael Lazar 4.5k Jun 3, 2021
:cherry_blossom: A command-line fuzzy finder

fzf is a general-purpose command-line fuzzy finder. It's an interactive Unix filter for command-line that can be used with any list; files, command hi

Junegunn Choi 37.1k Jun 6, 2021
A smart and nice Twitter client on terminal written in Python.

A Note about Twitter API Change Heads-up! As Twitter discontinues supporting Stream API, RainbowStream's stream function has been stopped working for

orakaro.targaryen 3.3k May 31, 2021
:duck: DuckDuckGo from the terminal

ddgr ddgr is a cmdline utility to search DuckDuckGo (html version) from the terminal. While googler is extremely popular among cmdline users, in many

Piña Colada 2.1k Jun 5, 2021
Notifies you when long-running terminal commands complete

undistract-me Notifies you when long-running terminal commands complete. What is this? Does this ever happen to you? You're doing some work, and as pa

Jonathan Lange 471 Jun 2, 2021
:bookmark: Browser-independent bookmark manager

buku buku in action! Introduction buku is a powerful bookmark manager written in Python3 and SQLite3. When I started writing it, I couldn't find a fle

Piña Colada 4.5k Jun 6, 2021
System monitoring dashboard for terminal

gtop System monitoring dashboard for terminal. Requirements Linux / OSX / Windows (partial support) Node.js >= v8 Installation $ npm install gtop -g D

Can Güney Aksakalli 8.5k Jun 5, 2021
Command-line program to download videos from YouTube.com and other video sites

youtube-dl - download videos from youtube.com or other video platforms INSTALLATION DESCRIPTION OPTIONS CONFIGURATION OUTPUT TEMPLATE FORMAT SELECTION

youtube-dl 95.9k Jun 5, 2021