Navigate Your Terminal Faster with Zoxide

// Before you start

What you need

A terminal (macOS Terminal, Linux shell, or Windows PowerShell / Git Bash)
Know which shell you use (bash, zsh, fish, or PowerShell are most common)
Internet connection to download the installer

Step 1 of 6

Install zoxide on your system

2 min

This downloads and installs the zoxide program. Pick the one command that matches your operating system. On macOS or Linux the curl script is the easiest option. On Windows, winget is the recommended route. You only need to run one of these.

Terminal · mac

$ # macOS or Linux (paste this in Terminal):

$ curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh

$ # macOS with Homebrew instead:

$ brew install zoxide

$ # Windows (paste in PowerShell):

$ winget install ajeetdsouza.zoxide

$ # Ubuntu / Debian / Raspbian:

$ sudo apt install zoxide

What you should see

A short download progress log ending with something like: 'zoxide: installed successfully to ~/.local/bin/zoxide'

This might happen

On Linux the installer puts zoxide in ~/.local/bin which may not be in your PATH yet

Add this line to your shell config file and restart the terminal: export PATH="$HOME/.local/bin:$PATH"

Step 2 of 6

Find your shell config file

1 min

You need to add one line to your shell's startup file so zoxide loads every time you open a terminal. First figure out which shell you are running. The command below prints the name.

Terminal · mac

$ echo $SHELL

What you should see

Something like /bin/zsh, /bin/bash, or /usr/bin/fish. On PowerShell you will see a Windows path instead.

Step 3 of 6

Add zoxide to your shell config

3 min

Copy the single line that matches your shell and paste it at the very bottom of your config file. The easiest way is to use the echo command below — it appends the line automatically without opening any editor. Pick only the command that matches your shell from step 2.

Terminal · mac

$ # Zsh (~/.zshrc):

$ echo 'eval "$(zoxide init zsh)"' >> ~/.zshrc

$ # Bash (~/.bashrc):

$ echo 'eval "$(zoxide init bash)"' >> ~/.bashrc

$ # Fish (~/.config/fish/config.fish):

$ echo 'zoxide init fish | source' >> ~/.config/fish/config.fish

$ # PowerShell (run echo $profile first to find the file, then open it and add):

$ Invoke-Expression (& { (zoxide init powershell | Out-String) })

What you should see

No output means success. The line was appended silently.

This might happen

Running the echo command twice will add the line twice, which causes a harmless but messy duplicate

Open the config file in a text editor and delete the duplicate line, then save

Step 4 of 6

Reload your shell so the change takes effect

1 min

Your terminal needs to re-read the config file you just edited. The easiest way is to close and reopen the terminal window. Or run the reload command below.

Terminal · mac

$ # Zsh or Bash:

$ source ~/.zshrc

$ # or

$ source ~/.bashrc

$ # Fish:

$ source ~/.config/fish/config.fish

$ # PowerShell: close and reopen the window

What you should see

No errors. Your prompt returns normally.

This might happen

You see 'command not found: zoxide' after reloading

Zoxide is not in your PATH. Run: export PATH="$HOME/.local/bin:$PATH" then source your config file again

Step 5 of 6

Build up your jump history by visiting folders

2 min

Zoxide learns from the directories you actually visit. Use the normal cd command (or the new z command) to navigate to a few folders you care about. After visiting them at least once, zoxide will remember them.

Terminal · mac

$ cd ~/Documents

$ cd ~/Downloads

$ cd ~/Desktop

What you should see

Your prompt changes to reflect each directory, exactly like normal cd.

Step 6 of 6

Jump to a folder with z

1 min

Now use z followed by any part of a folder name you have visited. Zoxide finds the best match and takes you there instantly. You do not need to type the full path or even the exact name — just a recognisable fragment.

Terminal · mac

$ z Documents

$ # or just a fragment:

$ z doc

$ # Jump back to the previous directory:

$ z -

$ # Interactive picker (requires fzf to be installed):

$ zi doc

What you should see

Your prompt changes to the matched directory, e.g. ~/Documents. If no match exists yet, zoxide prints 'zoxide: no match found'.

This might happen

'no match found' even though you visited the folder

You must use z (not cd) at least once to register a directory, OR cd into it first and then try z again — zoxide hooks into cd automatically after setup

// Status

cooked. baked. worked.

A working z command in your terminal that lets you jump to frequently visited folders by typing just a fragment of their name, saving you from typing long paths ever again.

// the honest bit

The honest part

Zoxide gets smarter the more you use it — on day one it has almost no history, so jumping feels limited. Give it a week of normal terminal use and it becomes genuinely useful. The interactive zi picker requires fzf to be installed separately (brew install fzf or apt install fzf). On Windows, PowerShell setup works well but Cygwin/Git Bash users may hit PATH quirks.