Claude Code: «command not found» y errores de instalación y PATH

Instalaste Claude Code, pero al escribir claude en la terminal aparece esto, ¿te suena?

zsh: command not found: claude                                         # macOS
bash: claude: command not found                                        # Linux
'claude' is not recognized as an internal or external command         # Windows CMD
claude : The term 'claude' is not recognized as the name of a cmdlet   # PowerShell

Este error significa «no se encuentra el ejecutable claude», y la causa suele ser «la carpeta de instalación no está en tu PATH». A menudo la instalación sí funcionó: simplemente la shell no sabe dónde buscar. Este artículo cubre los métodos de instalación y sus ubicaciones, cómo arreglar el PATH, los conflictos entre varias instalaciones, las trampas específicas de Windows y la actualización, todo contrastado con la documentación oficial a 29 de septiembre de 2026.

Los puntos clave por adelantado. (1) command not found casi siempre es solo «~/.local/bin (el directorio de instalación) no está en el PATH»: añádelo, reinicia la terminal y funciona. (2) Un error de permisos de npm (EACCES) NO se debe arreglar con sudo: cambia al instalador nativo en su lugar. (3) Cuando te atasques, ejecuta claude doctor: comprueba la salud de la instalación, la configuración y el resultado de la actualización de una sola vez. Los comandos exactos y los valores por defecto cambian según la versión, así que confirma lo más reciente en la documentación oficial.

1. Qué te está diciendo este error

Cuando escribes un comando, la shell (zsh / bash / PowerShell) busca las carpetas listadas en la variable de entorno PATH en orden y ejecuta el primer ejecutable que coincide. command not found: claude significa que ninguna de esas carpetas contenía claude.

Lo importante: no significa necesariamente que la instalación haya fallado. El instalador nativo coloca claude en ~/.local/bin (Windows: %USERPROFILE%\.local\bin), pero si esa carpeta no está en el PATH, el binario existe y aun así la shell no lo encuentra. Por eso la mayoría de los casos se resuelven con «añadir una línea al PATH y reiniciar la terminal». Antes de sospechar de una instalación fallida, ejecuta ls ~/.local/bin/claude para comprobar si el binario está ahí.

En Windows, usar la «shell equivocada» para el comando de instalación (por ejemplo, ejecutar el comando de PowerShell en CMD) produce errores distintos, que se tratan en el §4. Primero, fijemos los métodos de instalación correctos y sus ubicaciones.

2. Métodos de instalación y dónde queda el binario

Estos son los métodos de instalación que recoge la página oficial de instalación a 29 de septiembre de 2026, y dónde acaba el binario (se recomienda el instalador nativo).

El punto clave: el instalador nativo es el oficialmente recomendado. La versión de npm instala el mismo binario nativo. Desde la v2.1.198 el paquete de npm exige Node.js 22 o posterior, pero con un Node.js más antiguo npm solo muestra un aviso EBADENGINE y la instalación termina igualmente (el binario no usa Node para ejecutarse). La vía npm es más propensa a problemas de permisos y de PATH, así que si vas a instalar desde cero, lo nativo es la opción segura. Ten en cuenta que instalar solo la extensión de VS Code incluye una CLI privada dentro de la extensión y NO añade claude al PATH: si quieres claude en la terminal, instálalo por separado.

3. Causas principales y soluciones

Estas son las causas habituales en torno a command not found, emparejadas con sus soluciones.

Un arreglo concreto del PATH (zsh en macOS): echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc y luego source ~/.zshrc. En bash de Linux, lo mismo en ~/.bashrc; con bash en macOS, usa ~/.bash_profile (Terminal inicia bash como shell de inicio de sesión, que ignora ~/.bashrc). En PowerShell de Windows, añade la carpeta al PATH de usuario con [Environment]::SetEnvironmentVariable('PATH', "$([Environment]::GetEnvironmentVariable('PATH', 'User'));$env:USERPROFILE\.local\bin", 'User'). Tras el cambio, abre una nueva terminal y compruébalo con claude --version.

«Native installation exists but ~/.local/bin is not in your PATH»

Este aviso aparece en la salida de claude doctor (bajo «Installation warnings») y debajo del campo de entrada. Tal como lo han citado usuarios en los issues oficiales de GitHub, dice:

Native installation exists but ~/.local/bin is not in your PATH
Run: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc then open a new terminal or run: source ~/.zshrc

Significa que el binario nativo está en ~/.local/bin, pero esa carpeta no está en el PATH que ve Claude Code. El arreglo es el de arriba: añade la línea al archivo de configuración de tu shell y abre una nueva terminal. Si en una terminal nueva echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin" ya muestra la carpeta y el aviso sigue apareciendo, estás en un caso reportado en GitHub (#63695: PATH definido solo en ~/.zshenv y arranque desde la terminal de VS Code; #75431: claude instalado en otra ubicación). Ambos se cerraron sin corrección a 29 de septiembre de 2026. Si claude --version funciona en una terminal nueva, la instalación en sí está bien.

4. Trampas específicas de Windows

En Windows, el fallo clásico es ejecutar el comando de instalación en la «shell equivocada». El error te indica qué confusión ha ocurrido.

Otras notas de Windows: (1) Reinicia la terminal después de instalar (un cambio de PATH surte efecto en una terminal nueva). (2) Un Claude Desktop antiguo que registró WindowsApps\Claude.exe puede hacer que claude abra la aplicación de escritorio en lugar de la CLI: actualiza Claude Desktop. (3) Git for Windows es opcional: sin él, Claude Code ejecuta los comandos con su herramienta de PowerShell. Si Git está instalado pero no se encuentra Git Bash, apunta CLAUDE_CODE_GIT_BASH_PATH en la configuración a tu bash.exe. Ejecutarlo bajo WSL también es una opción.

VS Code: «Could not locate the Claude CLI on PATH»

La extensión de VS Code muestra este error en Windows cuando abres Claude Code en la terminal integrada, la shell de esa terminal es PowerShell y la extensión no encuentra el claude instalado en el PATH. El mensaje empieza así:

Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH.

La extensión bloquea el arranque porque llamar a claude por su nombre en PowerShell podría ejecutar un claude de la carpeta abierta en lugar de la CLI instalada. (1) Abre una nueva ventana de PowerShell fuera de VS Code y ejecuta where.exe claude; si no muestra nada, añade la carpeta de instalación al PATH como en la §3. (2) Pon la entrada del PATH en una variable de entorno de usuario o del sistema, no solo en tu perfil de PowerShell (la extensión no ejecuta tu perfil). (3) Reinicia VS Code, porque solo lee el PATH al arrancar.

«'claude' is not recognized» justo después de una actualización

Para actualizarse en Windows, Claude Code renombra el claude.exe existente como una copia de seguridad llamada claude.exe.old. más una marca de tiempo y coloca la nueva versión en su lugar. Si ese movimiento falla y el renombrado no se puede deshacer, en %USERPROFILE%\.local\bin queda la copia pero no hay claude.exe. Restaura la copia más reciente en PowerShell:

Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

Después compruébalo con claude --version. Si no hay ningún archivo claude.exe.old.*, reinstala con irm https://claude.ai/install.ps1 | iex. Desde la v2.1.281, una actualización fallida restaura automáticamente el ejecutable guardado.

5. Actualización automática y actualizar

Las instalaciones nativas se actualizan automáticamente en segundo plano y surten efecto en el siguiente arranque. Para actualizar manualmente usa claude update; para reinstalar/fijar una versión concreta usa claude install <version> (también acepta stable / latest). El resultado del último intento de actualización se ve con claude doctor. Las instalaciones con Homebrew, WinGet, apt, dnf y apk no se actualizan solas por defecto; en Homebrew y WinGet, si defines CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1, Claude Code ejecuta la actualización por ti.

«Auto-update failed · Run claude doctor»

Cuando falla una actualización en segundo plano, la sesión abierta lo muestra en su zona de estado. Los issues de GitHub citan dos formas: Auto-update failed · Run claude doctor (de la v2.1.220 a la v2.1.278) y, en instalaciones npm de versiones anteriores, Auto-update failed · Try claude doctor or npm i -g @anthropic-ai/claude-code. Resuélvelo en este orden:

1. Ejecuta claude doctor en una terminal: muestra el resultado del último intento de actualización y los avisos de instalación.
2. Ejecuta claude update para aplicar la actualización ahora. Responde Successfully updated from <old version> to version <new version>, o Claude Code is up to date (<version>) si no hay nada pendiente.
3. Si ya estás al día, el fallo fue pasajero (por ejemplo, un corte de red). Según issues de GitHub (#89286, #96038), el aviso puede seguir visible hasta reiniciar la sesión.
4. En una instalación global de npm cuya carpeta no admite escritura, la actualización automática no puede funcionar: pasa al instalador nativo (ver el recuadro de arriba).
5. Si falla una y otra vez en una red corporativa, comprueba que downloads.claude.ai sea accesible.

6. El flujo de diagnóstico

Cuando la causa no está clara, ve de arriba abajo. La mayoría de los casos se resuelven en el paso 3.

Resumen

El «command not found: claude» de Claude Code es, en la mayoría de los casos, solo «el directorio de instalación (~/.local/bin) no está en el PATH». El binario existe, así que añade una línea al PATH y reinicia la terminal y funcionará. Para instalar, el instalador nativo es el recomendado (la versión de npm pide Node.js 22+ y tiene más trampas de permisos/PATH). Un EACCES de npm se arregla cambiando a nativo, no con sudo.

Diagnostica con (1) claude doctor -> (2) which -a claude / where.exe claude para ver conflictos -> (3) añadir ~/.local/bin al PATH -> (4) eliminar versiones de más -> (5) reinstalación nativa. En Windows, vigila la confusión de shell (p. ej., irm en CMD), la necesidad de reiniciar la terminal y el conflicto del antiguo Claude Desktop Claude.exe. Actualiza con claude update / claude install y detén la actualización automática con DISABLE_AUTOUPDATER. Cuando te atasques, una reinstalación nativa es la solución fiable. Relacionado: Recopilación de errores de Claude Code, errores de autenticación / inicio de sesión.

FAQ

Q. Lo instalé, pero me sale command not found: claude.
A. Casi con total seguridad el directorio de instalación no está en tu PATH. Primero comprueba si el binario existe con ls ~/.local/bin/claude (Windows: %USERPROFILE%\.local\bin); si está ahí, añade export PATH="$HOME/.local/bin:$PATH" a ~/.zshrc/~/.bashrc y abre una nueva terminal. La instalación en sí suele haber funcionado.

Q. npm install -g falla con un error de permisos (EACCES).
A. No uses sudo npm (desaconsejado oficialmente; invita a problemas de permisos y seguridad). La vía más rápida y segura es cambiar al instalador nativo (mac/Linux: curl -fsSL https://claude.ai/install.sh | bash). La compilación nativa no tiene trampas de permisos y no necesita Node. También puedes mover el prefijo global de npm a un directorio con permisos de escritura para el usuario, pero la recomendación oficial es la nativa.

Q. Tengo varias instalaciones de claude y se ejecuta una versión antigua.
A. Ejecuta which -a claude (Windows: where.exe claude) para ver cada claude en el PATH. Puede que tengas npm-global, Homebrew, WinGet y nativo mezclados. Conserva la nativa (~/.local/bin) y elimina las demás (p. ej., npm uninstall -g @anthropic-ai/claude-code) para quedarte con una única instalación.

Q. En Windows, al escribir claude se abre la aplicación de escritorio.
A. Un Claude Desktop antiguo registró WindowsApps\Claude.exe, y este tiene prioridad en el PATH sobre la CLI. Actualiza Claude Desktop para resolverlo. Además, si no se encuentra o muestra una versión antigua tras ejecutar el instalador de PowerShell, reinicia la terminal para que surta efecto el cambio de PATH.

Q. Las actualizaciones no funcionan / quiero detenerlas.
A. Las instalaciones nativas se actualizan automáticamente en segundo plano y surten efecto en el siguiente arranque. De forma manual, usa claude update; para reinstalar/fijar, claude install <version>. Si aparece Auto-update failed · Run claude doctor, ejecuta claude doctor y luego claude update; si indica que ya estás al día, al reiniciar la sesión desaparece el aviso. Si la actualización automática falla en una instalación global de npm, es un problema de permisos de escritura: sigue claude doctor y migra a nativo. Para detener la actualización automática, define DISABLE_AUTOUPDATER en el env de la configuración; para bloquear todas las actualizaciones, define DISABLE_UPDATES.