Tutorial de Zoxide: Navegación de Terminal Más Inteligente (2026)

Zoxide reemplaza cd con un comando de salto que aprende qué directorios usas. Este tutorial de zoxide cubre v0.10.0 (publicada 2026-07-04): cómo instalarlo, la línea zoxide init para tu shell, y los comandos z y zi que hacen la navegación de terminal más rápida. También corrige los comandos que los tutoriales viejos hacen mal. El selector interactivo es zi, no z -i. Listar es zoxide query -l, no z -l. Y zoxide import ya no acepta --from. Todo lo de abajo está escrito para que lo corras esta noche y verifiques cada paso.

El problema con cd

cd es uno de los comandos esenciales de Linux que tecleas todo el día, y funciona bien hasta que tu árbol de directorios se hace profundo. Entonces empiezas a reescribir rutas largas, a completar con tab tres niveles, o a mantener un segundo terminal abierto solo para evitar volver atrás. El comando no es el problema. Tener que recordar y teclear rutas exactas sí lo es.

Existe una alternativa a cd más inteligente. Tarda unos cinco minutos en configurarse y no cuesta nada.

¿Qué es Zoxide?

Zoxide es una herramienta de línea de comandos que reemplaza a cd para la navegación de directorios. Está inspirada en herramientas como z y autojump, escrita en Rust, con licencia MIT, y con unas 40.000 estrellas en GitHub al 2026-10-07. Corre en Linux, macOS, Windows y BSD, y soporta Bash, Zsh, Fish, PowerShell, Nushell (v0.106.0+), Elvish (v0.18.0+), Tcsh, Xonsh, y cualquier shell POSIX (ksh incluido, vía zoxide init posix).

Zoxide es un rastreador de directorios. Un hook de shell registra los directorios que visitas y asigna a cada uno una puntuación de “frecency”, una mezcla de frecuencia y recencia. Cuanto más a menudo y más recientemente visites un directorio, más alto se posiciona en la base de datos.

Cómo funciona zoxide: el hook de shell registra cada directorio que visitas, las puntuaciones de frecency aterrizan en db.zo, los comandos z y zi consultan esas puntuaciones, y el shell salta a la mejor coincidencia

La base de datos es pequeña y local, pero es reutilizable. Gestores de archivos como yazi, lf, nnn, ranger, felix y superfile la leen nativamente, los usuarios de Neovim la obtienen por telescope-zoxide y zoxide.vim, y los selectores de sesión de tmux como tmux-sessionx, sesh y zesh saltan directo a tus directorios puntuados. Esa es la señal de una herramienta que se quedó: otras herramientas construyen sobre sus datos. También encaja en cualquier terminal que ya corras. Mira mi guía de configuración de Ghostty si a tus dotfiles les toca una renovación, o Integrando Wezterm, Zoxide y Tmux para el Terminal Mac Perfecto para un stack Mac completo.

En qué se diferencia Zoxide de cd

A diferencia de cd, zoxide aprende de tu comportamiento. No necesita nombres de ruta exactos. Predice a dónde quieres ir a partir de entradas parciales y tu historial de uso. Teclea z proj en vez de cd /home/user/code/work/clients/acme/project-api, y si project-api es el directorio que coincide con “proj” más a menudo y más recientemente, ahí aterrizas.

Beneficios de Zoxide

Las ventajas son reales pero pequeñas: un comando corto a cualquier directorio, palabras clave parciales en vez de rutas completas, y ningún mapa mental de árboles profundos que mantener.

Cómo instalar Zoxide

Instalar zoxide tarda unos minutos de extremo a extremo: instala el binario, añade una línea init a la config de tu shell, luego verifica con un salto de prueba.

Lo que necesitas:

Instala fzf junto a zoxide si quieres el selector interactivo. En macOS eso es brew install fzf; en Linux, usa el paquete de tu distro o los binarios de release de fzf. La versión mínima soportada de fzf es v0.51.0.

Instrucciones de instalación

En Windows, scoop install zoxide y choco install zoxide siguen funcionando si ya usas esos gestores. winget es simplemente la primera recomendación del README ahora. Para compilar desde fuente: cargo install zoxide --locked.

Tras instalar, comprueba la versión antes de seguir:

zoxide --version

Espera zoxide 0.10.x. Si ves 0.9.3 u 0.9.7, te llegó el paquete de la distro. Quítalo y reejecuta el script de instalación.

Añade Zoxide a tu shell (zoxide init)

La línea init debe ir al final del archivo rc de tu shell. El startup doctor comprueba la colocación del hook, y poner zoxide al final es lo que le hace ver cada cambio de directorio. Elige tu shell:

eval "$(zoxide init bash)"

eval "$(zoxide init zsh)"

zoxide init fish | source

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

zoxide init nushell | save -f ~/.zoxide.nu

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

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

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

Esa es toda la configuración. La base de datos empieza vacía y se rellena a medida que haces cd por ahí. Espera que el primer día o dos se sienta poco notable. Zoxide aún no tiene nada que posicionar. Después los saltos mejoran notablemente.

Verificando la instalación

Abre primero un shell nuevo (las líneas init no afectan a la sesión donde las añadiste), luego corre esto:

zoxide --version        # expect 0.10.x
type z                  # z is a shell function after init, which proves the hook loaded
mkdir -p ~/tmp/demo && cd ~/tmp/demo
cd ~ && z demo          # should land back in ~/tmp/demo
zoxide query -l         # the entry appears, sorted by frecency
pwd                     # confirm you are in ~/tmp/demo

Si type z reporta “not found”, la línea init no se está cargando. Comprueba que está al final del archivo rc correcto y que abriste un shell nuevo. Si z demo imprime zoxide: no match found, pasa un cd por el directorio primero para que quede registrado, y reintenta.

Usando Zoxide

Una vez zoxide está instalado y configurado, la superficie del día a día es pequeña: z, zi, y un puñado de subcomandos zoxide.

Saltando con z

El comando principal es z. Salta a un directorio usando solo parte de la ruta. Si visitas a menudo /home/user/projects/my_project:

z my_project

zoxide te lleva ahí, asumiendo que my_project puntúa más alto para esa palabra clave.

Es más listo que una coincidencia de nombre plana. Supón que tienes dos directorios:

• /home/user/projects/my_project
• /home/user/documents/my_project_report

Si has estado trabajando mayormente en el directorio de proyectos, z my_project va ahí. Si empiezas a trabajar más en el directorio del informe, z my_project normalmente empezará a favorecerlo en su lugar, porque frecency rastrea lo que hiciste recientemente.

Un comportamiento que vale conocer: si la query es una ruta exacta a la que se puede hacer cd, el wrapper z simplemente hace cd ahí y se salta la base de datos por completo. z ~/tmp/demo es un cd plano, no una búsqueda.

Selección interactiva con zi (fzf)

Cuando no estás seguro de qué directorio quieres, o varios coinciden, usa zi. Abre fzf sobre los directorios coincidentes y salta al que elijas.

zi proj

zi necesita fzf v0.51.0 o más nuevo. Ajusta el selector con _ZO_FZF_OPTS. En Fish, las completions Space-Tab (nuevas en 0.10.0) muestran y ejecutan el comando seleccionado. Si usas Fish y quieres selección interactiva integrada en el propio shell, mira autocompletado y sugerencias de Fish Shell. Un caveat: el terminal Warp no soporta las completions Space-Tab de zoxide. Warp trae su propio sistema de completion.

Referencia de comandos Zoxide

Esta es la tabla corregida. Las filas viejas z -l / z -i que encontrarás en otros sitios están mal.

zoxide edit no es un flag CLI para ajustar puntuaciones. Abre fzf sobre la base de datos para que podes entradas interactivamente. Si fzf no está instalado, falla con zoxide: could not find fzf, is it installed?.

Consejos para dominarlo

• Usa zoxide query -l (no z -l) para ver a dónde podría llevarte z, ordenado por frecency.
• Usa zoxide query -s cuando quieras ver por qué un directorio posiciona donde posiciona.
• Excluye árboles ruidosos con _ZO_EXCLUDE_DIRS para que nunca se conviertan en objetivos de salto.
• Poda entradas obsoletas con zoxide edit (o zoxide remove -i si prefieres elegir de una lista).
• Combínalo con fzf v0.51.0+ para zi y las completions Space-Tab.

Viniendo de z, Autojump o Atuin (zoxide import)

Si otra herramienta de salto ya acumuló un historial, no lo tires. zoxide import extrae bases de datos de los sospechosos habituales:

zoxide import z          # from z.sh
zoxide import zsh-z      # zsh-z support, new in 0.10.0
zoxide import autojump
zoxide import fasd
zoxide import z.lua
zoxide import atuin      # new in 0.10.0, pulls directories out of atuin shell history
zoxide import z --merge  # merge into the existing db instead of replacing

Los archivos de base de datos se autodetectan. Desde 0.10.0 la importación también respeta _ZO_EXCLUDE_DIRS, así que los árboles excluidos siguen excluidos.

Configurando Zoxide (variables de entorno y comandos personalizados)

Todo lo ajustable vive en variables de entorno _ZO_* y flags de zoxide init. Pon las variables en el mismo archivo rc, encima de la línea init.

Dos de estas sorprenden a la gente. _ZO_EXCLUDE_DIRS por defecto es $HOME: el propio home nunca es objetivo de salto, lo cual es intencional (no necesitas una herramienta fuzzy para llegar a ~). Y en Linux/macOS la lista de exclusión está separada por :, no por espacios.

Para los nombres de comando en sí, zoxide init toma flags:

• --cmd j: renombra los comandos (j / ji en vez de z / zi)
• --cmd cd: reemplaza cd por completo
• --no-cmd: define tus propias funciones a partir de __zoxide_z y __zoxide_zi
• --hook pwd (por defecto) / --hook prompt / --hook none: cuándo se actualiza la base de datos (en cada cambio de directorio, una vez por prompt, o nunca, solo con zoxide add manual)

Ejemplo, un setup j/ji en Bash:

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

Ubicación de la base de datos de Zoxide y backup

En Linux la base de datos es un solo archivo: ~/.local/share/zoxide/db.zo. Es diminuta. Unas pocas entradas son un puñado de bytes, e incluso años de uso se quedan en los KB bajos. No hay servicio, ni archivo de lock que vigilar, nada que migrar salvo ese único archivo.

Valores por defecto por SO (pisa con _ZO_DATA_DIR si quieres todo bajo ~/.config):

Una nota de versión que vale conocer: antes de v0.9.8 (2025-05-26), zoxide podía corromper su base de datos si el filesystem estaba al 100%. Eso está arreglado. Es también el argumento práctico contra correr el paquete 0.9.3 de Ubuntu 24.04 en algo que te importe.

Solución de problemas de Zoxide

zoxide: no match found significa que la base de datos está vacía (fase de aprendizaje) o tu palabra clave nunca coincidió. Comprueba zoxide query -l para ver lo que está registrado. Recuerda que las rutas exactas evitan la base de datos por diseño, _ZO_EXCLUDE_DIRS por defecto es $HOME, y _ZO_MAXAGE (10000) envejece las entradas viejas.

zoxide: could not find fzf significa que zi, zoxide edit y las completions Space-Tab carecen de su dependencia. Instala fzf v0.51.0+ y asegúrate de que está en tu PATH.

Un aviso del doctor en cada prompt significa que tu línea init no es lo último en tu archivo rc. Muévela al final. Si sabes lo que haces y quieres silencio: _ZO_DOCTOR=0.

Las completions de Zsh se comportan raro suele ser un compdump obsoleto. rm ~/.zcompdump* y luego arranca un shell nuevo (o reejecuta compinit).

Las completions Space-Tab en el terminal Warp no están soportadas; Warp corre su propio sistema de completion. z y zi siguen funcionando.

Los directorios con symlink se comportan raro debería parar tras v0.10.0, que arregló el manejo de rutas relativas a través de symlinks. Si quieres rutas canónicas en la base de datos, pon _ZO_RESOLVE_SYMLINKS=1.

zoxide import --from z fallando es esperado: el flag --from se eliminó en 0.10.0. Usa zoxide import z.

El paquete de Ubuntu es antiguo y no hay forma más amable de decirlo. Quítalo y reinstala con el script de instalación.

Hacer rollback es simple. Para soltar una entrada mala, corre zoxide remove <path> o zoxide remove -i. Para eliminar zoxide por completo: borra la línea init de tu archivo rc, brew uninstall zoxide (o el equivalente de tu plataforma), y borra el directorio de datos (~/.local/share/zoxide en Linux). Nada más del sistema se toca.

Zoxide y zsh-autocomplete

Combinar zoxide con zsh-autocomplete te da salto de directorios y autocompletado en tiempo real juntos. zsh-autocomplete es un plugin de Zsh que sugiere archivos, directorios y opciones de comandos mientras tecleas, así que memorizas menos y tecleas menos.

zsh-autocomplete está listado como soportado nativamente en la propia tabla de integraciones de zoxide. Sin código pegamento. zoxide funciona por defecto con Oh My Zsh: instálalo, añade la línea init al final de ~/.zshrc, listo. Para el lado de completion, sigue Cómo Activar el Autocompletado de Comandos en ZSH y tendrás ambos funcionando.

Alternativas a Zoxide

zoxide es la recomendación por defecto por una razón, pero las alternativas son reales y algunas están a una línea de distancia de importarse a zoxide más tarde.

z (Jump Around) es la herramienta que inspiró zoxide. Salta al directorio más ‘frecent’ que coincide con tus regexes. Script shell puro, sin binario. El mantenimiento lleva años tranquilo.

Autojump es un saltador más viejo basado en Python que usa nombres parciales y un algoritmo autoaprendizaje. Funciona, pero el desarrollo se frenó hace mucho.

fzf no es un saltador sino un fuzzy finder. Resuelve un problema distinto (elegir de cualquier lista), por eso zoxide lo usa para zi en vez de competir con él.

z.lua es un port a Lua enfocado en velocidad, con varios modos de coincidencia. Interesante si ya estás metido en un stack de config Lua.

fasd da acceso rápido tanto a archivos como a directorios, inspirado en autojump y v. Mayormente sin mantenimiento a estas alturas.

zsh-z es una reimplementación en Zsh puro de z, popular entre quienes quieren cero dependencias. zoxide puede importar su base de datos (zoxide import zsh-z).

atuin es una herramienta de historial de shell, no un saltador, pero sus datos ahora alimentan zoxide directamente (zoxide import atuin). Útil si tu historial ya sabe dónde has estado.

Mi default es zoxide: un único binario estático, todos los shells que uso están soportados, y el formato de base de datos es útil a otras herramientas. Si te niegas a instalar un binario, zsh-z es el fallback.

FAQ

Conclusión

Zoxide 0.10.0 (publicada 2026-07-04) hace la navegación de terminal más rápida puntuando los directorios que usas y saltando a ellos desde una palabra clave parcial. El historial de versiones vale conocerlo cuando lees otras guías: el startup doctor automático aterrizó en 0.9.7 (2025-02-09), el soporte Tcsh, zoxide add --score y el arreglo de corrupción de base de datos aterrizaron en 0.9.8 (2025-05-26), y 0.10.0 añadió importación de atuin, manejo de $CDPATH en z, y binarios Linux RISC-V. Corre en Bash, Zsh, Fish, PowerShell, Nushell (v0.106.0+), Elvish (v0.18.0+), Tcsh, Xonsh, y cualquier shell POSIX.

El setup son tres pasos: instala vía el script (o brew/pacman/winget), pon la línea zoxide init al final de tu archivo rc, y verifica con type z más un salto de prueba. Luego deja de teclear rutas largas.

Zoxide también funciona con Fish Shell. Si te interesa probar Fish, mira los mejores plugins de Fish Shell (zoxide está incluido) o mi comparación Fish Shell vs Bash vs Zsh.