Instalación y primer arranque

Neovim casi no trae nada dentro, y eso no es un defecto: es la decisión que lo mantiene pequeño, rápido y portable. Busca con ripgrep, clona con git, compila parsers con tu compilador de C y entiende tu código con servidores que son programas aparte. La consecuencia la vas a sufrir antes de acabar la semana: un fallo casi nunca se manifiesta donde está la causa. El buscador aparece vacío y culpas al plugin; falta fd. El LSP no responde y revisas tu Lua media hora; el servidor no está instalado. Esta lección instala el editor, y sobre todo instala el reflejo que resuelve esa clase entera de problemas.

• Instalar 0.12.4 o superior, y saber por qué la versión no es negociable aquí.
• Enumerar los binarios externos y qué deja de funcionar si falta cada uno.
• Localizar con stdpath() dónde viven de verdad tu config, tus datos y tu estado.
• Leer un :checkhealth sabiendo qué secciones existen y cuáles ignorar.
• Reiniciar sin salir con :restart, y aislar experimentos con NVIM_APPNAME.

Lo primero: el editor no hace casi nada solo

Neovim orquesta. Casi nada de lo que parece «una función del editor» vive dentro de él.

Todo lo naranja es un programa que tú tienes que tener instalado, y cada paso te dice —púlsalo— qué deja de funcionar si falta. Esa es la tabla de diagnóstico que vas a usar durante años.

Y por eso los fallos aparecen lejos de su causa

Esa arquitectura es lo que hace al editor pequeño y portable, y es también la razón de que un fallo casi nunca se manifieste donde está el problema.

El buscador se abre vacío y piensas que el plugin está roto: lo que pasa es que fd no está en el PATH. El resaltado no aparece y revisas tu config treinta minutos: falta el compilador de C. El LSP no responde y culpas a la configuración: el servidor no está instalado.

Adopta el reflejo hoy: cuando algo no funcione, la primera pregunta no es «qué opción me falta» sino «qué binario le falta al editor». Esa respuesta la da :checkhealth en cinco segundos, y quien la ejecuta antes de abrir el navegador se ahorra la mayoría de las tardes perdidas de las que se queja todo el mundo.

Instalar Neovim

0.12 no es opcional en esta guía

Comprueba con nvim --version que tienes 0.12 o superior — la estable actual es la 0.12.4, publicada el 5 de julio de 2026.

No es purismo. vim.pack, el gestor de plugins integrado, es de 0.12. La opción 'autocomplete' es de 0.12. La rama viva de nvim-treesitter exige 0.12.0 como mínimo, y lo dice en su README. Con 0.11 buena parte de la guía no te va a funcionar.

Los gestores de paquetes van atrasados con frecuencia. Si el tuyo te da 0.10 u 0.11, usa el binario oficial.

macOS

brew install neovim git ripgrep fd fzf lazygitbrew install tree-sitter          # el CLI, lo exige la rama main de nvim-treesitterbrew install node                 # varios servidores de lenguaje son de Node

macOS ya trae compilador de C con las Command Line Tools. Si te falta:

xcode-select --install

Linux (Debian / Ubuntu)

El repositorio oficial suele ir muy atrasado. Usa el tarball oficial —hay uno por arquitectura, y también AppImage si prefieres no instalar nada—:

curl -LO https://github.com/neovim/neovim/releases/latest/download/nvim-linux-x86_64.tar.gzsudo rm -rf /opt/nvim-linux-x86_64sudo tar -C /opt -xzf nvim-linux-x86_64.tar.gz# añade al final de ~/.bashrc o ~/.zshrcexport PATH="$PATH:/opt/nvim-linux-x86_64/bin"

En ARM el artefacto es nvim-linux-arm64.tar.gz. Y las dependencias:

sudo apt install git curl tar ripgrep fd-find build-essential

tree-sitter-cli: ni con npm, ni con cargo si no tienes Rust

El README de nvim-treesitter es explícito: la versión 0.26.1 o superior, «instalada con tu gestor de paquetes, no con npm». No da ninguna razón, pero la recomendación es literal.

En Debian y Ubuntu no está en los repositorios oficiales, así que tienes tres vías reales: el binario de las releases de tree-sitter/tree-sitter, cargo install tree-sitter-cli si ya tienes Rust instalado —no lo instalan los pasos de arriba—, o un gestor como nix, pacman o brew si lo usas en Linux.

Y en Debian, fd se instala como fdfind. Haz un enlace, porque los plugins buscan fd:

ln -s $(which fdfind) ~/.local/bin/fd

Windows

winget install Neovim.Neovimwinget install BurntSushi.ripgrep.MSVC sharkdp.fd Git.Git

winget install acepta varios identificadores separados por espacios y los instala en secuencia. Lo que no admite es mezclarlos con --id o --version: para eso, un comando por paquete.

En Windows, WSL2 te ahorra meses

Para desarrollo serio, instala Neovim dentro de WSL2. Muchos plugins y servidores asumen rutas y herramientas de Unix, y en WSL2 todo funciona sin fricción. La alternativa nativa es viable pero vas a pelearte con casos que nadie más tiene.

Qué necesita cada cosa

git

vim.pack clona y actualiza plugins llamando a git. Sin git no hay plugins.

ripgrep

El motor del grep de proyecto. Sin él, buscar texto en el proyecto no encuentra nada.

fd

Búsqueda de ficheros respetando .gitignore. Sin él, el picker aparece vacío.

Compilador de C

Los parsers de Treesitter se compilan en tu máquina. Sin él, no hay resaltado por árbol.

tree-sitter-cli + curl + tar

Descargan y generan los parsers. Los tres los exige la rama main de nvim-treesitter.

Node.js

TypeScript, Tailwind, ESLint y varios servidores más son programas de Node.

Dónde vive todo: stdpath()

Antes de crear un solo fichero conviene saber dónde los busca el editor, porque a partir del Nivel 2 esto deja de ser trivia: la carpeta lsp/ desde la que se configuran los servidores, la after/ que sobreescribe a las demás y el sitio donde vim.pack clona los plugins son todos rutas derivadas de aquí.

:lua vim.print(vim.fn.stdpath('config'))   " ~/.config/nvim:lua vim.print(vim.fn.stdpath('data'))     " ~/.local/share/nvim:lua vim.print(vim.fn.stdpath('state'))    " ~/.local/state/nvim:lua vim.print(vim.fn.stdpath('cache'))    " ~/.cache/nvim

En macOS también son rutas XDG, no ~/Library

Es un error muy repetido: Neovim no usa ~/Library/Application Support en macOS. La tabla de :h standard-path solo distingue Unix de Windows, y macOS es Unix a estos efectos. Tu config está en ~/.config/nvim/ igual que en Linux.

En Windows nativo sí cambia: ~/AppData/Local/nvim/.

NVIM_APPNAME: probar sin romper lo tuyo

NVIM_APPNAME=prueba nvim hace que el editor use prueba en lugar de nvim en todas las carpetas base: config, datos, estado y caché. No es solo un cambio de config: es una instalación paralela y aislada.

Es la forma de probar una distribución entera, de reproducir el bug de otra persona o de comparar dos configuraciones sin tocar la tuya. Existe desde 0.9 y va a aparecer varias veces en esta guía.

Cómo arranca Neovim

Merece la pena ver el orden, porque explica la mitad de los «¿por qué no se aplica mi configuración?» que tendrás más adelante.

La pieza que hay que retener de este diagrama tiene nombre: runtimepath. Es una lista ordenada de directorios donde Neovim busca todo lo que no está compilado dentro: plugins, ficheros de tipo, sintaxis, documentación y —a partir del Nivel 3— las fichas de configuración de los servidores de lenguaje.

:set runtimepath?:echo $VIMRUNTIME

Verás algo así: tu carpeta de configuración primero, luego $VIMRUNTIME —el runtime que vino con el binario—, y al final las carpetas after/ de cada una. Ese orden es la regla entera: se lee de arriba abajo, y after/ va el último, así que lo que pongas ahí gana. Cuando en el Nivel 3 quieras cambiar un detalle de la configuración de un servidor sin reescribirla, la respuesta será exactamente esta.

Dentro de cada directorio del runtimepath, los nombres importan

No es una carpeta libre: Neovim busca subdirectorios con nombres concretos y los trata distinto.

No tienes que crear ninguno hoy. Pero cuando en el Nivel 2 escribas require("config.options"), funcionará porque lua/ de tu carpeta de configuración está en el runtimepath, y no por magia.

Arrancar de otra manera

nvim a secas no es la única forma, y tres de estas te van a salvar una tarde.

nvim --clean arranca como una instalación recién hecha: sin tu configuración, sin tus plugins y sin tocar tu histórico. Es la primera pregunta ante cualquier problema: si el fallo desaparece con --clean, el fallo es tuyo o de un plugin, y acabas de partir el espacio de búsqueda por la mitad. Si sigue, es del editor o de tu terminal.

nvim --clean                  # como recién instaladonvim -u NONE fichero          # sin config y sin pluginsnvim -u NORC fichero          # sin config, pero con pluginsnvim --startuptime tiempo.log # apunta cuánto tarda cada paso del arranque

Y un puñado de argumentos que ahorran comandos una vez dentro:

El del guion suelto es el más infravalorado: cualquier salida de cualquier comando se puede volcar en un buffer y navegarla con todo lo que sabes, en vez de pelearla en el terminal.

Que el sistema entero use Neovim

Muchos programas abren un editor cuando lo necesitan —git commit, crontab -e, visudo— y consultan dos variables de entorno. Ponlas en tu ~/.bashrc o ~/.zshrc:

export EDITOR=nvimexport VISUAL=nvim

A partir de ahí, escribir el mensaje de un commit o resolver un rebase interactivo ocurre dentro de Neovim, con tu configuración. Es de los cambios de una línea que más se notan.

Si vienes de Vim

Tu .vimrc no se lee: la configuración va en ~/.config/nvim/init.lua. La forma corta de reutilizar la que ya tienes está documentada en :h nvim-from-vim, y consiste en añadir tu ~/.vim al runtimepath y hacer source de tu .vimrc desde el init.vim.

Funciona, y aun así la recomendación de esta guía es empezar de cero en el Nivel 2. Buena parte de un .vimrc típico son opciones que Neovim ya trae puestas y plugins que el núcleo ya sustituyó; arrastrarlo entero es heredar el trabajo de configurar cosas que ya no hay que configurar.

Leer un :checkhealth

Arranca nvim y ejecuta :checkhealth. Sale un informe largo, y aquí es donde casi todo el mundo se pierde. Lo primero es saber que el informe está partido en secciones con nombre, y que puedes pedir una sola.

:checkhealth vim.health        " solo el núcleo:checkhealth vim.lsp           " solo el LSP:checkhealth vim*              " todas las de Neovim

:checkhealth vim da error, y no es un fallo tuyo

vim.health es a la vez el nombre del framework con el que los plugins escriben sus comprobaciones y el nombre de la comprobación del núcleo. El editor excluye el framework del listado, así que :checkhealth vim responde No healthchecks found. La sección del núcleo se pide entera: :checkhealth vim.health.

Y si has leído en algún sitio que hay una sección llamada nvim, está caducado: se eliminó, y si autoload/health/nvim.vim sigue en tu $VIMRUNTIME el propio informe te lo marcará como resto de una instalación vieja.

vim.deprecated merece que la mires desde el primer día, aunque hoy no tengas configuración. Es la sección que te dice si estás usando vim.loop en vez de vim.uv, vim.highlight en vez de vim.hl o vim.tbl_flatten en vez de Iter:flatten(). Como casi todo el material que circula por internet está escrito para versiones anteriores, esta sección es el detector automático de código copiado de un tutorial viejo.

Lo que puedes ignorar

Los providers de Python, Ruby, Perl y Node aparecen en rojo casi siempre, y casi siempre da igual: son la compatibilidad con plugins antiguos escritos en esos lenguajes. Con una configuración moderna no usas ninguno.

Si te molesta verlos, se apagan poniéndolos a cero:

vim.g.loaded_python3_provider = 0vim.g.loaded_ruby_provider = 0vim.g.loaded_perl_provider = 0vim.g.loaded_node_provider = 0

A cero, no a uno

Es el error más repetido de esta parte, y Neovim 0.12 llegó a añadir un aviso específico para él: «para desactivar el provider, ponlo a 0, no a 1». Un 1 no lo desactiva.

Y si algún día ves E319: No "python3" provider found, el mensaje ya te dice dónde mirar: :checkhealth vim.provider.

La Nerd Font

Muchos plugins muestran iconos, y sin una Nerd Font —una fuente parcheada con miles de glifos— verás cuadraditos.

# macOSbrew install --cask font-jetbrains-mono-nerd-font

En Linux y Windows, descárgala de nerdfonts.com y configúrala en tu terminal, no en Neovim: es tu emulador quien decide con qué fuente se pinta todo. Neovim solo pide que la fuente tenga los glifos; la fuente, el emulador y los colores del terminal son tu entorno, no el editor.

Recargar sin salir

Vas a reiniciar Neovim cien veces al día cuando empieces a tocar la config. Desde 0.12 no hace falta cerrar y abrir:

:restart

Hace tres cosas en orden: cierra con :qall, arranca un servidor nuevo con los mismos argumentos, y reengancha las interfaces al nuevo. En modo Normal tienes el equivalente ZR, también nuevo en 0.12.

Dos detalles de :restart que te van a pasar

El primer paso es un :qall, así que con buffers modificados aborta. Para reiniciar descartando cambios: :restart +qall!, o directamente 1ZR —con conteo, ZR no comprueba modificaciones—.

Y no restaura tu sesión: los buffers abiertos no vuelven. Si quieres eso, la propia documentación enseña el truco: :mksession! Session.vim | restart source Session.vim.

¿Dónde va a vivir la config?

En stdpath('config'), es decir ~/.config/nvim/. El fichero raíz es init.lua. Todavía no existe: lo creas en el Nivel 2, después de haber aprendido a usar el editor sin él.

vimtutor: media hora que no se salta

nvim +Tutor

Es el tutorial interactivo oficial y es la mejor inversión de tiempo de toda esta guía: veinticinco o treinta minutos tecleando dentro de un documento que te va guiando y comprobando.

No lo dejes para luego pensando «ya lo leeré». Lo que enseñan las dos lecciones siguientes —el modelo modal y la gramática— no se aprende leyendo: se aprende con los dedos, y el tutor es el sitio donde equivocarte sin consecuencias.

Checklist de instalación

1. nvim --version muestra 0.12 o superior.
2. Ejecuta :set runtimepath? y localiza tu carpeta de configuración, $VIMRUNTIME y las entradas after/. Ese orden es la regla que gobierna todo lo que instales de aquí en adelante.
3. Arranca con nvim --clean y comprueba que el editor sigue funcionando. Guárdalo: es la primera pregunta ante cualquier fallo futuro.
4. Exporta EDITOR=nvim y haz un git commit sin -m para verlo abrirse.
5. :checkhealth vim.health no reporta errores en git, rg, curl ni el compilador. Fíjate en que la sección se llama así y no nvim.
6. Ejecuta :checkhealth vim.deprecated. Hoy debería estar limpia; anota el comando, porque será lo primero que mires cuando copies código de internet.
7. Ejecuta :checkhealth vim.pack y localiza dónde va a vivir el lockfile. Aún no has instalado ningún plugin y la sección ya existe.
8. Comprueba las rutas: :lua vim.print(vim.fn.stdpath('config'), vim.fn.stdpath('data'), vim.fn.stdpath('state')). Si estás en macOS, verifica que no aparece ~/Library.
9. Prueba :restart. Después abre un fichero, escribe algo sin guardar y vuelve a probarlo: comprobarás que aborta. Reinicia entonces con 1ZR.
10. Arranca con NVIM_APPNAME=prueba nvim y ejecuta :lua vim.print(vim.fn.stdpath('config')). La ruta ha cambiado: acabas de tener dos instalaciones aisladas.
11. Tu terminal usa una Nerd Font: :echo nr2char(0xf07b) debe mostrar un icono de carpeta, no un cuadro.
12. Completa al menos la mitad de nvim +Tutor.
13. Y una comprobación del reflejo: desinstala mentalmente ripgrep y pregúntate qué dejaría de funcionar. Si sabes responder, has entendido esta lección.