Índice
Instalaste Claude Code, pero al escribir claude en la terminal aparece esto, ¿te suena?
zsh: command not found: claude
bash: claude: command not found
'claude' is not recognized as an internal or external command # WindowsEste 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 basado en información oficial.
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.
Instalado, pero no se encuentra
— el directorio de instalación simplemente no está en el PATH
El binario sí existe. Solo que el PATH de la shell no incluye su ubicación.
Así que la solución es «añadir una línea al PATH»: normalmente menos de un minuto.
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 principales métodos de instalación a fecha de 2026 y dónde acaba el binario (se recomienda el instalador nativo).
| Método | Comando (forma) | Ubicación / nota |
|---|---|---|
| Nativo (recomendado) mac/Linux | curl -fsSL https://claude.ai/install.sh | bash | ~/.local/bin/claude. Se actualiza solo |
| Nativo (recomendado) Windows | En PowerShell: irm https://claude.ai/install.ps1 | iex | %USERPROFILE%\.local\bin\claude.exe |
| npm | npm install -g @anthropic-ai/claude-code | Requiere Node 18+. Instala el mismo binario nativo |
| Homebrew (mac) | brew install --cask claude-code | Sin actualización automática → brew upgrade |
| WinGet (Windows) | winget install Anthropic.ClaudeCode | Sin actualización automática → winget upgrade |
El punto clave: el instalador nativo es el oficialmente recomendado. La versión de npm instala el mismo binario nativo (Node 18+ solo se necesita en el momento de la instalación; el binario no necesita Node para ejecutarse), pero es más propensa a problemas de permisos y de PATH. 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.
Principales causas de instalación / PATH
~/.local/bin está fuera del PATH. Añade export PATH="$HOME/.local/bin:$PATH" a ~/.zshrc/~/.bashrc y reinicia la terminal.sudo npm (desaconsejado oficialmente). Cambiar al instalador nativo es la solución más rápida y segura.which -a claude (Win: where.exe claude) y deja solo la nativa.Could not find native binary package ... aparece cuando instalaste con las dependencias opcionales omitidas. Reinstala sin --omit=optional ni similares.
En caso de duda, «reinstalar con el instalador nativo» resuelve la mayoría de estos casos:
esquiva de un golpe los problemas de permisos, Node y conflictos.
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. Tras el cambio, abre una nueva terminal.
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.
Cómo detectar la confusión de shell
| Error | Significado y solución |
|---|---|
'irm' is not recognized ... | Ejecutaste el comando de PowerShell en CMD → usa PowerShell: irm ... | iex |
The token '&&' is not valid | Ejecutaste el comando de CMD en PowerShell → usa el comando de CMD |
'bash' is not recognized ... | Ejecutaste el instalador de Linux en Windows → usa el instalador de PowerShell |
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) Si 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.
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). Comprueba el resultado de la actualización con claude doctor.
Cuando la actualización automática falla en la instalación de npm
Si la carpeta global de npm no tiene permisos de escritura, la actualización automática falla. claude doctor enumera las soluciones, y la solución de fondo es migrar a una instalación nativa. Para únicamente detener la actualización automática, define DISABLE_AUTOUPDATER en el env de la configuración (las actualizaciones manuales siguen funcionando); para bloquear todas las actualizaciones, define DISABLE_UPDATES.
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.
Aíslalo de arriba abajo
claude doctor (desde la shell si no arranca) para comprobar la salud de la instalación.which -a claude / where.exe claude para ver dónde y cuántas hay instaladas (¿conflictos?).~/.local/bin al PATH y reinicia la terminal.
La regla: «¿existe el binario → está en el PATH → hay conflicto?» en ese orden.
Cuando te atasques, una reinstalación nativa es el último recurso fiable.
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 necesita Node 18+ 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 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.
