zoxide: tus carpetas, a un par de letras

0:00 / 22:58 1×

Más formatos

Sabes que la carpeta existe. La has abierto esta mañana. Pero no recuerdas la ruta completa, así que empiezas a escribir cd, a pulsar Tab y a corregir. Otra vez.

zoxide hace justo eso por ti: recuerda las carpetas que visitas y te lleva a ellas con z y un par de letras. Es un cd con memoria, no un navegador de archivos ni un buscador de contenido. Funciona en Linux, macOS y Windows, guarda su base de datos en local y no necesita internet.

En este post vas a ver cómo instalarlo, cómo usarlo a diario, cómo configurarlo sin romper el ranking, cómo migrar desde autojump o z y cuándo no merece la pena. También he medido cuánto tarda una consulta y cuánto añade al arranque del shell, porque “es muy rápido” no es un dato.

El ejemplo está hecho con zoxide 0.10.0, publicado en julio de 2026, y fzf 0.74.5. La demo usa una base de datos temporal para no tocar la real.

1. El problema: cd no recuerda nada

cd es predecible: le das una ruta y te lleva. Si la ruta es larga, la escribes entera o usas Tab. Si no te acuerdas, la buscas. Y si cambias mucho entre tres o cuatro proyectos, repites el mismo camino varias veces al día.

1
2
3

cd ~/proyectos/cliente-a/api
cd ~/proyectos/cliente-b/web
cd ~/proyectos/cliente-a/api

No hay nada malo en ello. El problema es el coste acumulado: teclas, correcciones y cambios de contexto. zoxide ataca ese coste con una idea sencilla: si ya has estado ahí, la herramienta se acuerda por ti.

1
2
3

z api
z web
z api

La primera vez tienes que visitar la carpeta con cd o añadirla con zoxide add. A partir de ahí, z busca en su base de datos local y salta a la coincidencia mejor puntuada.

2. Qué hace zoxide y qué no

zoxide es un binario escrito en Rust, inspirado por z y autojump, que se integra en tu shell. No sustituye al shell: le añade una función z (y zi) que consulta una base de datos y hace cd por ti.

Hace tres cosas:

• Registra las carpetas que visitas.
• Puntúa cada una según cuántas veces y cuándo la has visitado.
• Resuelve consultas como z api y te lleva a la mejor coincidencia.

No hace:

• Buscar dentro de los archivos. Para eso están rg, fd o bat.
• Explorar el sistema de archivos como un gestor visual.
• Adivinar una carpeta que nunca has visitado.
• Ser una dependencia para tus scripts. z es una función del shell interactivo; en un script se usa zoxide query.

La base de datos es tuya y vive en local. No hay cuenta, no hay telemetría y no hay peticiones a un servidor. Eso sí: guarda rutas completas, así que conviene excluir lo que no quieras tener ahí.

3. Cómo decide a dónde ir

La consulta no es una búsqueda difusa sobre todo el disco. Es un filtro sencillo y predecible sobre las rutas que ya conoces.

3.1 Matching: los términos van en orden

Las reglas, sacadas de la wiki del algoritmo:

• La búsqueda no distingue mayúsculas.
• Todos los términos tienen que aparecer en la ruta, en orden.
• El último término tiene que aparecer en el último componente de la ruta.
• Si hay varias coincidencias, gana la de mayor frecuencia.

Ejemplos:

1
2
3
4

z api          → /home/cris/proyectos/cliente-a/api
z cliente api  → /home/cris/proyectos/cliente-a/api
z api /        → una subcarpeta que empieza por api
z bar          → /foo/bar, pero no /bar/foo

Ese detalle del último componente es el que hace que z bar no te lleve a cualquier ruta que contenga “bar”. También explica por qué z cliente b puede encontrar .../cliente-b/web: la b aparece en el último componente.

3.2 Puntuación: frecuencia más recencia

Cada carpeta empieza con una puntuación de 1. Cada visita suma 1. Al consultar, la puntuación se multiplica según cuándo fue la última visita:

El ranking no es solo frecuencia: una carpeta que visitaste hace un mes baja aunque la hayas usado mucho.

Cuando el total de puntuaciones supera _ZO_MAXAGE, zoxide divide las puntuaciones y elimina las que quedan por debajo de 1. No es un número de días: es un presupuesto de score. Lo veremos en la configuración.

3.3 También hay zi

z elige la mejor coincidencia y se mueve. zi abre un selector con fzf para que elijas tú cuando hay varias. Es la diferencia entre “confío en el ranking” y “quiero ver las opciones”.

z es directo; zi añade una parada para elegir. Ninguno de los dos cambia de shell.

4. Instalación y primer salto

4.1 Instalar el binario

En Arch Linux:

1

sudo pacman -S zoxide

En macOS:

1

brew install zoxide

En Windows, con PowerShell:

1

winget install ajeetdsouza.zoxide

En Debian/Ubuntu, el paquete de apt existe, pero suele ir muy por detrás. El propio proyecto recomienda el script oficial en esas distribuciones:

1

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

El script se ejecuta con sh. Si no quieres pipe-to-shell, descárgalo, léelo y ejecútalo después. Es la misma precaución que aplicarías a cualquier instalador.

También puedes usar cargo install zoxide --locked desde crates.io, conda, scoop o choco. La lista completa está en el README del proyecto.

4.2 Cargarlo en el shell

La línea va al final del fichero de configuración del shell. En zsh, después de compinit, o las completaciones no funcionarán.

1
2

# ~/.bashrc
eval "$(zoxide init bash)"

1
2

# ~/.zshrc
eval "$(zoxide init zsh)"

1
2

# ~/.config/fish/config.fish
zoxide init fish | source

1
2

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

Abre una terminal nueva y comprueba que el binario y la función están ahí:

1
2

zoxide --version
type z

La primera debería responder con la versión; la segunda, decir que z es una función.

4.3 El primer salto

Visita unas cuantas carpetas con cd para que zoxide aprenda:

1
2
3
4

cd ~/proyectos/blog
cd ~/proyectos/api-server
cd ~/proyectos/cliente-a/api
cd ~/proyectos/cliente-b/web

Ahora prueba:

1
2
3

z blog
z api
z cliente b

Si quieres ver lo que ha aprendido sin moverte:

1

zoxide query --list --score

Primeros pasos con una base de datos temporal: versión, consulta, salto y ranking.

Si z no encuentra nada, no es un error de zoxide: la carpeta no está en la base de datos. Entra una vez con cd o añádela con zoxide add /ruta/a/carpeta.

5. Los comandos del día a día

Estos son los que vas a usar de verdad:

El autocompletado con Tab es especialmente cómoda: escribes z api, pulsas espacio y Tab, y aparece el mismo selector de zi sin cambiar de comando.

5.1 Consultar sin moverte

1
2
3

zoxide query --list --score
zoxide query --list --score api
zoxide query api

• --list muestra todas las coincidencias, no solo la primera.
• --score añade la puntuación.
• Sin --list, zoxide query api devuelve la ruta que ganaría y termina.

zoxide query api es útil en scripts: no cambia de directorio y devuelve la ruta por stdout. Si no hay coincidencia, sale con código de error.

5.2 Añadir, borrar y editar

1
2
3

zoxide add ~/proyectos/cliente-a/api
zoxide remove ~/proyectos/antiguo
zoxide edit

• zoxide add registra una carpeta sin tener que entrar en ella.
• zoxide remove la saca de la base de datos; si vuelves a entrar, puede volver.
• zoxide edit abre la base de datos en tu editor para revisarla a mano. Úsalo con cuidado: es un fichero, no una interfaz.

5.3 Una sesión real

1
2
3
4
5
6
7
8

demo> z blog
/home/cristian/proyectos/zoxide-demo/blog
demo> z api
/home/cristian/proyectos/zoxide-demo/api-server
demo> z cliente b
/home/cristian/proyectos/zoxide-demo/trabajo/cliente-b/web
demo> z -
/home/cristian/proyectos/zoxide-demo/trabajo/cliente-a/api

Los saltos no dependen de que la carpeta esté cerca: pueden cruzar todo el disco. Esa es la diferencia frente a un cd relativo y frente a un z que solo mira el árbol actual.

Varias palabras, consulta del ranking y limpieza de la base de datos.

6. zi y fzf: elegir cuando hay dudas

zi es la versión interactiva. Necesita fzf instalado:

1
2
3
4
5
6
7
8

# Debian/Ubuntu
sudo apt install fzf

# macOS
brew install fzf

# Arch
sudo pacman -S fzf

Después:

1
2

zi
zi api

zi api abre una lista con las carpetas que contienen “api”, ordenadas por frecuencia, y te deja filtrar y elegir. Es la opción correcta cuando z api te lleva a la carpeta equivocada porque hay varias con el mismo nombre.

6.1 No rompas el ranking con _ZO_FZF_OPTS

Este es el error más fácil de cometer. Muchas guías proponen:

1

export _ZO_FZF_OPTS="--height=60% --layout=reverse --border"

El problema: _ZO_FZF_OPTS sustituye las opciones por defecto que zoxide pasa a fzf. Entre ellas está --no-sort, que mantiene el orden de frecuencia. Si lo quitas, fzf reordena por su propia puntuación y una carpeta con score 8 puede aparecer por encima de una con score 16.

Si quieres cambiar solo la altura, parte de la lista completa de opciones o usa FZF_DEFAULT_OPTS para tus otros flujos de fzf. FZF_DEFAULT_OPTS no cambia zi; _ZO_FZF_OPTS sí. La guía de configuración avanzada de zoxide.org tiene la lista exacta y ejemplos probados.

No copies un _ZO_FZF_OPTS de un blog sin comprobar que conserva --no-sort y el preview. Si el selector te enseña las carpetas desordenadas, has perdido la principal ventaja de zoxide.

7. Configuración: seis variables y tres flags

zoxide tiene una superficie de configuración pequeña. Esta es la que importa:

Las variables se leen antes de zoxide init. Si las pones después, la función z que ya está cargada no las ve.

7.1 _ZO_EXCLUDE_DIRS: cuidado con los globs

El valor por defecto excluye $HOME. Para excluir node_modules en cualquier proyecto, no basta con /node_modules:

1
2
3
4
5

# mal: solo excluye /node_modules en la raíz del disco
export _ZO_EXCLUDE_DIRS="$HOME:/node_modules"

# bien: excluye la carpeta en cualquier profundidad y su contenido
export _ZO_EXCLUDE_DIRS="$HOME:*/node_modules:*/node_modules/*"

En Linux y macOS el separador es :; en Windows, ;. Un patrón que termina en /* excluye los hijos, no la carpeta. Por eso hacen falta los dos patrones.

7.2 _ZO_MAXAGE no son días

_ZO_MAXAGE es el presupuesto total de score, no una fecha de caducidad. Si la suma de todos los scores lo supera, zoxide divide las puntuaciones y poda las que quedan por debajo de 1. El máximo teórico de entradas es 4 × _ZO_MAXAGE, aunque en la práctica suele ser menor.

7.3 Flags de zoxide init

Un ejemplo de zsh:

1
2
3
4

export _ZO_DATA_DIR="$HOME/.local/share/zoxide"
export _ZO_ECHO=1
export _ZO_EXCLUDE_DIRS="$HOME:*/node_modules:*/node_modules/*"
eval "$(zoxide init zsh)"

Si usas --cmd cd, recuerda que en fish el config.fish también se lee en scripts. Para no romper scripts, envuelve el init:

1
2
3

if status is-interactive
    zoxide init --cmd cd fish | source
end

8. Migrar desde autojump, z, fasd o atuin

No empiezas de cero. zoxide 0.10 puede importar la base de datos de otras herramientas:

1
2
3
4
5
6

zoxide import autojump --merge
zoxide import z --merge
zoxide import zsh-z --merge
zoxide import z.lua --merge
zoxide import fasd --merge
zoxide import atuin --merge

• En 0.10, import acepta un subcomando y autodetecta el fichero de origen.
• --merge es obligatorio si tu base de datos ya tiene entradas; sin él, la importación se niega.
• Las rutas que coinciden con _ZO_EXCLUDE_DIRS se saltan al importar.
• En 0.9 la sintaxis era zoxide import --from z ~/.z --merge y solo soportaba autojump y z.

Antes de importar, haz una copia de db.zo:

1

cp ~/.local/share/zoxide/db.zo ~/.local/share/zoxide/db.zo.bak

9. zoxide frente a cd, autojump, z, fzf e historial

No son herramientas excluyentes. La pregunta es qué tipo de salto estás haciendo.

9.1 Lo que no convence a todos

zoxide no es perfecto para todo el mundo. En Hacker News hay una crítica recurrente: convierte tus rutas en atajos que cambian con el tiempo. Si el ranking cambia, z api puede llevarte a otra carpeta, y eso obliga a comprobar dónde has caído. Para quien trabaja con rutas muy parecidas, Tab y el historial pueden ser más predecibles.

También hay una diferencia importante con z y z.lua: zoxide usa una lista global de frecuencia y no tiene en cuenta la carpeta actual. Si casi siempre te mueves dentro del mismo árbol, un cd relativo o un z que mire el contexto puede ser más rápido. Si saltas entre proyectos muy separados, la lista global es justo lo que quieres. Y si lo que buscas no es una carpeta sino algo que ya has leído, Hister juega otra liga.

9.2 Cuándo no usarlo

• En scripts. z es una función del shell interactivo. En un script usa zoxide query y comprueba el código de salida.
• En cuentas compartidas. La base de datos guarda rutas completas; pueden revelar nombres de proyectos o clientes.
• Para una ruta que solo visitas una vez. El coste de aprenderla no compensa.
• Si necesitas reproducibilidad estricta. Un atajo que depende de tu historial no es una ruta canónica.
• Si tu shell no es compatible. zoxide cubre los principales, pero no todos.

10. ¿Ralentiza el shell?

No de forma perceptible. He medido en un AMD Ryzen 7 8745HS con zoxide 0.10.0, usando hyperfine, 30 ejecuciones y la mediana:

El init añade unos 1,9 ms al arranque de un zsh limpio. La consulta sobre 10.000 entradas tarda 3,45 ms. Son cifras de esta máquina, no universales: servirán para que sepas el orden de magnitud, no para comparar portátiles.

La base de datos es un fichero local (db.zo) y no hay red. La consulta lanza el binario zoxide como subproceso; por eso ves milisegundos y no microsegundos. Si tu prompt ya tarda 200 ms por plugins, esto no se nota.

10.1 Privacidad

• La base de datos guarda rutas absolutas. Si trabajas con clientes, revisa zoxide query --list y excluye lo que no quieras.
• _ZO_EXCLUDE_DIRS se aplica al registrar y al importar.
• Puedes mover la base de datos con _ZO_DATA_DIR a un disco cifrado.
• No hay telemetría ni cuenta. La contrapartida es que la base de datos es tu responsabilidad: haz copia antes de importar o editar.

11. Cuando el salto falla

zoxide: no match found. La carpeta no está en la base de datos. Entra con cd o usa zoxide add.

zsh avisa de un problema de configuración. Algo después del init ha reemplazado el hook. Mueve eval "$(zoxide init zsh)" al final de ~/.zshrc.

El autocompletado con Tab no hace nada en zsh. El init está antes de compinit. Muévelo debajo y reconstruye la caché:

1
2

rm -f ~/.zcompdump*
compinit

zi no abre el selector. fzf no está instalado o es demasiado antiguo. Comprueba fzf --version y actualízalo.

--cmd cd rompe un script en fish. config.fish se lee también en scripts; envuelve el init en if status is-interactive.

En Windows o WSL las rutas no coinciden. Revisa que estás en el mismo entorno (PowerShell, Git Bash, WSL) y que zoxide y el shell comparten la misma base de datos. _ZO_DATA_DIR ayuda a fijarla.

He movido una carpeta y el atajo sigue apuntando al sitio viejo. zoxide poda entradas que ya no existen y son antiguas, pero puedes forzar la limpieza con zoxide remove o editar la base de datos.

12. Recetas y checklist

12.1 Tres formas de integrarlo

La conservadora: deja cd como está y usa z solo cuando te convenga. Cuando llegues, puedes listar con eza o abrir un archivo con bat.

1

eval "$(zoxide init bash)"

La total: sustituye cd por zoxide. cd sigue funcionando con rutas exactas, pero además aprende.

1

eval "$(zoxide init --cmd cd bash)"

La personalizada: crea tus propios comandos y decide tú cuándo se registra.

1

eval "$(zoxide init --cmd j --hook prompt bash)"

12.2 Checklist

• zoxide --version responde.
• type z dice que es una función.
• Has visitado varias carpetas y zoxide query --list las muestra.
• z y zi hacen lo que esperas.
• fzf está instalado si usas zi.
• _ZO_EXCLUDE_DIRS excluye lo que no quieres guardar.
• Sabes dónde está db.zo y cómo hacer una copia.
• No usas z en scripts; usas zoxide query.

13. Enlaces y vídeos de interés

13.1 Artículos

• Jump between directories with zoxide — la guía corta y completa que me sirvió de punto de partida.
• Using zoxide – smarter cd command for Linux/macOS — instalación y primeros pasos con capturas.
• zoxide Tutorials — tutoriales por tarea, con configuración avanzada y fzf.

13.2 Vídeos

Dreams of Autonomy: cómo zoxide cambia la navegación diaria en el terminal.

Chris Titus Tech: “Stop using the CD Command”, una demo práctica de zoxide.

Coding in Public: instalación, z y zi en menos de seis minutos.