zoxide-romanized

zoxide-romanized is the multi-language romanization edition of zoxide. It provides the shared romanizer framework. Chinese pinyin is the first and currently only implemented language, with full-pinyin and initials matching. The design allows additional language romanizers to be added independently.

• z shichang matches 市场 by full pinyin.
• z sc matches 市场 by pinyin initials.
• z sy2 matches 实验2, preserving the numeric suffix.
• Polyphonic readings are considered for both full pinyin and initials.

The installed executable and shell command remain zoxide / z.

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

Read more about the matching algorithm here.

Installation

The primary multi-language crate currently enables pinyin by default:

cargo install zoxide-romanized --locked

zoxide-pinyin is the Chinese-only edition. It disables the primary crate's default features and enables only pinyin, so future language features in the primary crate will not be included:

cargo install zoxide-pinyin --locked

Install only one crate. Both install the executable named zoxide. If Cargo reports that an existing zoxide binary would be overwritten, use cargo install zoxide-romanized --locked --force to replace it. Prebuilt builds from this fork, when available, are listed on the Lineance releases page. On Unix, the installer fetches the matching fork build:

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

The shell setup remains the usual zoxide init command. Your existing zoxide shell configuration and database are reused automatically because this fork uses the same executable name and data directory. Legacy db.zo databases are migrated to db.txt on first read; no manual conversion is needed.

1. 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.106.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) })

   Tcsh

   Add this to the end of your config file (usually ~/.tcshrc):

   zoxide init tcsh > ~/.zoxide.tcsh
   source ~/.zoxide.tcsh

   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)"

   Note: [Warp] provides its own completions, so Space+Tab completions are not supported there.

2. Install fzf ^(optional)

   fzf is a command-line fuzzy finder, used by zoxide for completions / interactive selection. It can be installed from here.

   Note: The minimum supported fzf version is v0.51.0.

3. Import your data ^(optional)

   If you currently use any of these plugins, you may want to import your data into zoxide. The data file is auto-detected using each plugin's standard conventions.

   zoxide import <plugin>

   Plugin	Command
   atuin	zoxide import atuin
   autojump	zoxide import autojump
   fasd	zoxide import fasd
   z	zoxide import z
   z.lua	zoxide import z.lua
   zsh-z	zoxide import zsh-z

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 (default)	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.

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/zoxide or $HOME/.local/share/zoxide	/home/alice/.local/share/zoxide
    macOS	$HOME/Library/Application Support/zoxide	/Users/Alice/Library/Application Support/zoxide
    Windows	%LOCALAPPDATA%\zoxide	C:\Users\Alice\AppData\Local\zoxide

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

Romanization features

zoxide-romanized is the multi-language edition and provides the shared romanizer framework. Pinyin is currently the only implemented language and is enabled by default. ASCII letters and digits can be mixed in a romanized query (for example, sy2 matches 实验2). Future language romanizers can be exposed as separate Cargo features.

zoxide-pinyin is a focused Chinese edition. It depends on zoxide-romanized with default features disabled and enables only the pinyin feature. This keeps the pinyin package independent of future romanizer features. Both packages install the same zoxide executable; install only one.

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
raycast	macOS launcher	raycast-zoxide
rfm	File manager	Natively supported
sesh	tmux session manager	Natively supported
superfile	File manager	Natively supported
telescope.nvim	Fuzzy finder for Neovim	telescope-zoxide
tmux-session-wizard	tmux session manager	Natively supported
tmux-sessionx	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
zesh	zellij session manager	Natively supported
zsh-autocomplete	Realtime completions for zsh	Natively supported

Footnotes

1. If you're not sure how to set an environment variable on your shell, check out the wiki. ↩