---
name: "zoxide"
section: "1"
platform: "linux"
package: "zoxide"
version: "0.10.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/zoxide"
---

# zoxide(1)

a smarter cd command

## NAME

**zoxide** - a smarter cd command

## SYNOPSIS

**zoxide SUBCOMMAND \[OPTIONS\]**

## DESCRIPTION

zoxide is a smarter cd command for your terminal. It keeps track of the directories you use most frequently, and uses a ranking algorithm to navigate to the best match.

## USAGE

```
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 (bash 4.4+/fish/zsh only)
```

## SUBCOMMANDS

- [**zoxide-add**(1)](/zoxide-add/1.md)

  Add a new directory to the database, or increment its rank.

- [**zoxide-import**(1)](/zoxide-import/1.md)

  Import entries from another application.

- [**zoxide-init**(1)](/zoxide-init/1.md)

  Generate shell configuration.

- [**zoxide-query**(1)](/zoxide-query/1.md)

  Search for a directory in the database.

- [**zoxide-remove**(1)](/zoxide-remove/1.md)

  Remove a directory from the database.

## OPTIONS

- **-h, --help**

  Print help information.

- **-V, --version**

  Print version information.

## ENVIRONMENT VARIABLES

Environment variables can be used for configuration. They must be set before [**zoxide-init**(1)](/zoxide-init/1.md) is called.

- **\_ZO\_DATA\_DIR**

  Specifies the directory in which the database is stored. The default value varies across OSes:

  | | |
  | --- | --- |
  | **OS** | Path |
  | **Linux/BSD** | **$XDG\_DATA\_HOME** or **$HOME/.local/share**, eg. **/home/alice/.local/share** |
  | **macOS** | **$HOME/Library/Application Support**, eg. **/Users/Alice/Library/Application Support** |
  | **Windows** | **%LOCALAPPDATA%**, eg. **C:\\Users\\Alice\\AppData\\Local** |

- **\_ZO\_ECHO**

  When set to 1, **z** will print the matched directory before navigating to it.

- **\_ZO\_EXCLUDE\_DIRS**

  Prevents the specified directories from being added to the database. This is provided as a list of globs, separated by OS-specific characters:

  | | |
  | --- | --- |
  | **OS** | Separator |
  | **Linux/macOS/BSD** | **:**, eg. **$HOME:$HOME/private/\*** |
  | **Windows** | **;**, eg. **$HOME;$HOME/private/\*** |

  By default, this is set to **$HOME**. After setting this up, you might need to use [**zoxide-remove**(1)](/zoxide-remove/1.md) to remove any existing entries from the database.

- **\_ZO\_FZF\_OPTS**

  Custom options to pass to [**fzf**(1)](/fzf/1.md) during interactive selection. See the manpage for the full 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.

## ALGORITHM

- **AGING**

  zoxide uses a parameter called **\_ZO\_MAXAGE** to limit the number of entries in the database based on usage patterns. If the total **FRECENCY** of the directories in the database exceeds this value, we divide each directory's score by a factor **k** - such that the new total becomes ~90% of **\_ZO\_MAXAGE**. Thereafter, if the new score of any directory falls below 1, it is removed from the database.

  Theoretically, the maximum number of directories in the database is **4 \* \_ZO\_MAXAGE**, although it is lower in practice.

- **FRECENCY**

  Each directory in zoxide is given a score, starting with 1 the first time it is accessed. Every subsequent access increases the score by 1. When a query is made, we calculate frecency based on the last time the directory was accessed:

  | | |
  | --- | --- |
  | **Last access time** | **Frecency** |
  | Within the last hour | score \* 4 |
  | Within the last day | score \* 2 |
  | Within the last week | score / 2 |
  | Otherwise | score / 4 |

## REPORTING BUGS

For any issues, feature requests, or questions, please visit:

**https://github.com/ajeetdsouza/zoxide/issues**

## AUTHOR

Ajeet D'Souza **\<98ajeet@gmail.com\>**