--- title: "Tutorial de Zoxide: Navegación de Terminal Más Inteligente (2026)" description: "Tutorial de Zoxide: instala y configura el comando cd más inteligente para Bash, Zsh, Fish y más. Aprende z, zi y los comandos zoxide para saltar entre directorios rápido." date: 2026-10-07 categories: ["linux"] tags: ["zoxide","terminal","cli"] --- import Button from "@components/widgets/Button.astro"; import Notice from "@components/widgets/Notice.astro"; import ListCheck from "@components/widgets/ListCheck.astro"; import Accordion from "@components/widgets/Accordion.astro"; import Tabs from "@components/widgets/Tabs.astro"; import Tab from "@components/widgets/Tab.astro"; import { Picture } from "astro:assets"; import imag1 from "@assets/images/24/02/zoxide-tutorial.gif"; 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](/linux-commands/) 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](https://github.com/ajeetdsouza/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](@assets/images/24/02/zoxide-how-it-works.svg) 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](/es/terminal-ghostty/) si a tus dotfiles les toca una renovación, o [Integrando Wezterm, Zoxide y Tmux para el Terminal Mac Perfecto](https://www.bitdoze.com/install-wezterm-mac/) 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. | Lo que obtienes | Comando `cd` | `zoxide` | | ----------------- | ------------ | --------------------- | | Entrada de ruta | Ruta exacta | Palabra clave parcial | | Aprende del uso | No | Sí (frecency) | | Configuración | Nada | Una línea init | | Datos extra guardados | Ninguno | `db.zo` local | Zoxide es gratis, licencia MIT, y totalmente local. Sin cuenta, sin daemon, sin telemetría, sin API key. Es una adición de coste cero a cualquier estación de trabajo o VPS. Útil cuando vives en sesiones SSH en una máquina barata como [Hetzner Cloud](https://go.bitdoze.com/hetzner) (la clase de 4-5 EUR/mes es de sobra). El único coste real es el minuto que toma añadir la línea init. ## 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. No hagas `sudo apt install zoxide` en Debian ni Ubuntu. El README oficial tacha esas distros por una razón: sus paquetes se actualizan muy despacio. Ubuntu 24.04 (noble) sigue enviando zoxide 0.9.3-1 al 2026-10-07: sin startup doctor, sin soporte Tcsh, sin el arreglo de corrupción de base de datos de 0.9.8, nada de 0.10.0. Ubuntu 25.10 envía 0.9.7-1, aún dos versiones minor detrás. Usa el script de instalación de abajo. ### Instrucciones de instalación | Sistema Operativo | Shell | Comando de Instalación | | --------------------- | ---------- | ------------------------------------------------ | | macOS | bash/zsh | `brew install zoxide` | | Linux (Debian/Ubuntu) | cualquiera | `curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh \| sh` | | Linux (Arch) | bash/zsh | `sudo pacman -S zoxide` | | Windows | PowerShell | `winget install ajeetdsouza.zoxide` | | Cualquiera | Cualquiera | `curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh \| sh` | 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: ```bash 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: Añade al final de `~/.bashrc`: ```bash eval "$(zoxide init bash)" ``` Añade al final de `~/.zshrc`: ```bash eval "$(zoxide init zsh)" ``` Zoxide funciona nada más instalar con Oh My Zsh. Solo añade la línea init. Si estás montando un setup de Zsh, mira los [mejores plugins de Oh My Zsh](/best-oh-my-zsh-plugins/) para qué más vale activar en 2026. Añade a `~/.config/fish/config.fish`: ```fish zoxide init fish | source ``` PowerShell, final de `$profile`: ```powershell Invoke-Expression (& { (zoxide init powershell | Out-String) }) ``` Nushell (mínimo v0.106.0 a partir de zoxide 0.10.0), luego hazle source en tu config: ```nu zoxide init nushell | save -f ~/.zoxide.nu ``` Tcsh (`~/.tcshrc`), dos líneas en vez de un eval de una línea: ```tcsh zoxide init tcsh > ~/.zoxide.tcsh source ~/.zoxide.tcsh ``` Xonsh (`~/.xonshrc`): ```python execx($(zoxide init xonsh), 'exec', __xonsh__.ctx, filename='zoxide') ``` Cualquier shell POSIX (dash, ksh): ```sh 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: ```bash 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. Estos comandos exactos se corrieron contra el binario 0.10.0 el 2026-10-07. `type z` devuelve una función de shell, `z demo` salta a un directorio recién visitado, y `zoxide query -l` lo lista. Usuarios de Zsh: si las completions se comportan mal tras instalar, `rm ~/.zcompdump*` y reejecuta `compinit`. ## 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`: ```bash 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. ```bash zi proj ``` Los tutoriales viejos muestran `z -i` para el modo interactivo. Ese comando no existe. `z -i` pasa `-i` a la búsqueda como palabra clave, así que obtienes `zoxide: no match found`. El comando interactivo es `zi`, un wrapper de `zoxide query --interactive`. Misma historia para `z -l`: usa `zoxide query -l`. `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](/es/fish-shell-autocompletado-sugerencias/). 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. | Comando | Descripción | | ------------------------------------ | ---------------------------------------------------------------------------- | | `z ` | Salta al directorio de mayor frecency que coincide con la query | | `zi ` | Selecciona un directorio interactivamente con fzf (requiere fzf) | | `zoxide query -l` | Lista todos los directorios coincidentes, ordenados por frecency | | `zoxide query -s` | Imprime la puntuación de frecency junto a cada resultado | | `zoxide query --base-dir ` | Restringe la búsqueda a un árbol de directorios | | `zoxide query --exclude ` | Excluye una ruta de la coincidencia | | `zoxide remove ` | Elimina un directorio de la base de datos | | `zoxide remove -i` | Elige interactivamente entradas a eliminar | | `zoxide edit` | Editor interactivo de la base de datos basado en fzf (requiere fzf) | `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. `zoxide doctor` no es un subcomando. Correrlo imprime `error: unrecognized subcommand 'doctor'`. El doctor es una función de shell que `zoxide init` define, y corre automáticamente en tu primer prompt (Bash y Zsh desde v0.9.7, shells POSIX desde v0.9.8). Si tu línea init no está al final de tu archivo rc, avisa: *"Please ensure that zoxide is initialized right at the end of your shell configuration file (usually ~/.bashrc). Disable this message by setting `_ZO_DOCTOR=0`."* Arregla la colocación, o acepta la pista y pon `_ZO_DOCTOR=0`. ## 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: ```bash 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. `zoxide import` ahora toma un subcomando, no un flag `--from`. El viejo `zoxide import --from z` desapareció. Si tienes snippets viejos en tus dotfiles o scripts de bootstrap, actualízalos a `zoxide import z` antes de subir de versión. ## 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. | Variable | Por defecto | Efecto | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `_ZO_DATA_DIR` | Linux/BSD: `$XDG_DATA_HOME/zoxide` o `~/.local/share/zoxide`; macOS: `~/Library/Application Support/zoxide`; Windows: `%LOCALAPPDATA%\zoxide` | Dónde vive la base de datos | | `_ZO_EXCLUDE_DIRS` | `$HOME` | Lista glob de directorios a nunca posicionar (separada por `:` en Linux/macOS) | | `_ZO_MAXAGE` | `10000` | Tope de envejecimiento de las entradas de la base de datos | | `_ZO_RESOLVE_SYMLINKS` | off | Guarda rutas canónicas en vez de las con symlinks (funciona en Windows desde 0.10.0) | | `_ZO_ECHO` | off | Imprime el directorio coincidente antes de saltar | | `_ZO_FZF_OPTS` | none | Opciones extra de fzf para `zi` | | `_ZO_DOCTOR` | `1` | Pon `0` para silenciar el startup doctor | 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: ```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. Añade `db.zo` a lo que ya uses para dotfiles o backups: un repo git, restic, o un job de sync a S3. Copiar el archivo a una máquina nueva lleva tu historial de frecency contigo, así que `z` funciona desde el día uno en vez de reaprender durante una semana. Valores por defecto por SO (pisa con `_ZO_DATA_DIR` si quieres todo bajo `~/.config`): | SO | Ubicación por defecto | | ----------- | ------------------------------------------------- | | Linux / BSD | `~/.local/share/zoxide/db.zo` (o `$XDG_DATA_HOME/zoxide`) | | macOS | `~/Library/Application Support/zoxide/db.zo` | | Windows | `%LOCALAPPDATA%\zoxide\db.zo` | 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](#instrucciones-de-instalación). **Hacer rollback** es simple. Para soltar una entrada mala, corre `zoxide remove ` 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.