Cómo instalar Claude Code en Windows, Linux y macOS

Qué es Claude Code y qué vas a instalar

«Instalar Claude» puede significar cosas distintas, y conviene aclararlo antes de escribir un comando. Claude Code es la herramienta que se ejecuta en la terminal y trabaja directamente sobre los archivos de tu proyecto: lee el código, propone cambios, ejecuta comandos y usa Git. Es la única de las formas de usar Claude que necesita una instalación y una puesta en marcha reales.

Según la documentación oficial, Claude Code también está disponible en la web, como aplicación de escritorio para macOS, Windows y Linux, dentro de VS Code y JetBrains, en Slack y en integración continua con GitHub Actions y GitLab. Si lo que buscás es conversar con Claude en un navegador, no necesitás nada de esta guía. Si preferís una interfaz gráfica sin tocar la terminal, la aplicación de escritorio te deja usar Claude Code sin línea de comandos.

Esta guía cubre la interfaz de línea de comandos, que es la que se instala una vez y después se invoca desde cualquier carpeta con el comando claude.

Requisitos: equipo y cuenta

Hay dos listas de requisitos y la segunda es la que más sorpresas da.

Lo que necesita tu equipo

No aparece Node.js en esa lista, y no es un olvido: el instalador nativo descarga un binario propio que no usa Node.js en tiempo de ejecución. Solo hace falta si elegís la vía de npm.

Lo que necesita tu cuenta

Este es el punto donde más gente se frena. El plan gratuito de Claude.ai no incluye Claude Code. La documentación exige una de estas opciones:

• una suscripción Pro, Max, Team o Enterprise;
• una cuenta de la Consola de Anthropic, con crédito prepago; en el primer inicio de sesión se crea automáticamente un espacio de trabajo llamado «Claude Code» para el seguimiento de costos;
• acceso a través de un proveedor externo: Amazon Bedrock, Google Cloud's Agent Platform o Microsoft Foundry.

Instalación en macOS

Abrí la Terminal y ejecutá el instalador nativo:

curl -fsSL https://claude.ai/install.sh | bash

No hace falta sudo. El instalador coloca el lanzador en ~/.local/bin/claude como un enlace simbólico hacia ~/.local/share/claude/versions/, que es donde conviven las versiones instaladas.

Alternativa: Homebrew

Si ya administrás tu software con Homebrew, hay dos casks disponibles:

# Canal estable: va aproximadamente una semana por detrás
brew install --cask claude-code

# Canal latest: recibe cada versión apenas se publica
brew install --cask claude-code@latest

El canal estable omite las versiones con regresiones importantes. La contrapartida de Homebrew es que no se actualiza solo: hay que ejecutar brew upgrade claude-code —o claude-code@latest, según cuál hayas instalado— para recibir correcciones de seguridad.

Instalación en Linux

El comando es el mismo que en macOS:

curl -fsSL https://claude.ai/install.sh | bash

Alternativa: repositorios firmados

Anthropic publica repositorios apt, dnf y apk firmados, con dos canales cada uno: stable y latest. Estos ejemplos configuran el canal estable en Debian y Ubuntu:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://downloads.claude.ai/keys/claude-code.asc \
  -o /etc/apt/keyrings/claude-code.asc
echo "deb [signed-by=/etc/apt/keyrings/claude-code.asc] \
https://downloads.claude.ai/claude-code/apt/stable stable main" \
  | sudo tee /etc/apt/sources.list.d/claude-code.list
sudo apt update
sudo apt install claude-code

Antes de confiar en la clave, verificá su huella digital. Tiene que coincidir exactamente con este valor:

gpg --show-keys /etc/apt/keyrings/claude-code.asc
# 31DD DE24 DDFA B679 F42D  7BD2 BAA9 29FF 1A7E CACE

Para Fedora y RHEL existe el equivalente con dnf, y para Alpine con apk. Las instalaciones por gestor de paquetes tampoco se actualizan solas: llegan con la actualización normal del sistema.

Alpine y otras distribuciones con musl

Alpine no trae bash ni curl de fábrica, así que el comando documentado falla con un error de «no encontrado» hasta que los instales. Además hacen falta libgcc, libstdc++ y ripgrep en tiempo de ejecución:

apk add bash curl libgcc libstdc++ ripgrep

Después hay que desactivar el ripgrep incorporado añadiendo USE_BUILTIN_RIPGREP con valor "0" dentro de la clave env del archivo settings.json. En Alpine, ripgrep está en el repositorio community: si apk dice que falta el paquete, hay que agregar ese repositorio y volver a intentar.

Instalación en Windows

En Windows hay una decisión previa: instalarlo de forma nativa o dentro de WSL. La documentación resume así las diferencias:

Opción 1: Windows nativo

Antes de copiar nada, fijate en qué consola estás. PowerShell muestra PS C:\ al principio de la línea; CMD muestra C:\ sin el PS. Es la causa número uno de los errores de instalación en Windows.

irm https://claude.ai/install.ps1 | iex

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

No hace falta ejecutar la consola como administrador. Existe también WinGet, con winget install Anthropic.ClaudeCode, que tampoco se actualiza solo: hay que ejecutar winget upgrade Anthropic.ClaudeCode cada tanto.

Git for Windows: opcional, pero cambia el comportamiento

Instalar Git for Windows es opcional y determina con qué intérprete ejecuta comandos Claude Code:

• Sin Git for Windows: usa la herramienta de PowerShell.
• Con Git for Windows: usa Git Bash para la herramienta Bash, lo que resulta cómodo si trabajás con scripts pensados para Bash.

Si lo instalaste pero Claude Code no lo encuentra, se le puede indicar la ruta desde settings.json con la variable CLAUDE_CODE_GIT_BASH_PATH apuntando al bash.exe de tu instalación de Git.

Opción 2: WSL

Si elegís WSL, abrí la terminal de tu distribución y usá el instalador de Linux. La instalación y el comando claude viven dentro de WSL, no en PowerShell ni en CMD. Si todavía no tenés WSL, se activa siguiendo la documentación oficial de Microsoft.

Verificar que quedó bien instalado

Terminada la instalación, cerrá y volvé a abrir la terminal —el PATH se lee al iniciar— y ejecutá:

claude --version

Una instalación correcta imprime un número de versión seguido de (Claude Code). Si querés un diagnóstico más completo, existe un comando que revisa la instalación y la configuración sin abrir una sesión:

claude doctor

Informa el estado de la instalación, los errores de validación de los archivos de configuración y las advertencias con su sugerencia de arreglo. Es lo primero que conviene ejecutar cuando algo no anda.

Iniciar sesión

Ejecutá claude y seguí las indicaciones: se abre el navegador para completar la autenticación. Las credenciales quedan guardadas y no hay que repetir el proceso en cada sesión.

Dos detalles que ahorran tiempo:

• Si tenés definida la variable de entorno ANTHROPIC_API_KEY, Claude Code no abre el navegador: te pide una vez que apruebes esa clave y la usa en lugar de tu suscripción. Es una fuente habitual de confusión cuando quedó una clave vieja en el perfil de la terminal.
• Para cambiar de cuenta o volver a autenticarte más adelante, se escribe /login dentro de la sesión.

La primera sesión

Posicionate en el proyecto y arrancá:

cd /ruta/a/tu/proyecto
claude

Vas a ver el indicador de Claude Code con la versión, el modelo y el directorio de trabajo. La documentación oficial sugiere empezar pidiéndole que lea antes de pedirle que escriba: preguntas como «¿qué hace este proyecto?», «¿qué tecnologías usa?» o «explicá la estructura de carpetas» sirven para verificar que entiende el código antes de dejarlo tocar nada. No hace falta agregar archivos al contexto a mano: los lee cuando los necesita.

Los comandos que vas a usar todos los días

Permisos: quién decide qué se modifica

En el modo por defecto, Claude Code pide aprobación antes de cada cambio en un archivo. Con Shift+Tab se rota entre los modos de permisos: uno que acepta las ediciones automáticamente y otro de planificación, en el que propone cambios sin escribir nada. Algunas cuentas disponen además de un modo automático con una comprobación de seguridad en segundo plano.

Otros atajos útiles: escribir / lista todos los comandos, Tab autocompleta y la flecha ↑ recorre el historial.

Configurar el proyecto con CLAUDE.md

Cada sesión empieza con el contexto vacío. Para que Claude Code no vuelva a preguntar lo mismo, se escriben instrucciones persistentes en un archivo CLAUDE.md, que se carga al inicio de cada conversación.

Puede vivir en varios lugares, con distinto alcance:

La forma más rápida de empezar es el comando /init: analiza el repositorio y genera un CLAUDE.md inicial con los comandos de compilación y prueba y las convenciones que encuentra. Si ya existe uno, propone mejoras en lugar de sobrescribirlo.

La documentación recomienda mantenerlo por debajo de las 200 líneas y escribir instrucciones concretas y verificables: «usar indentación de 2 espacios» funciona mejor que «formatear bien el código». Un archivo más largo consume más contexto y reduce el nivel de cumplimiento. Conviene revisarlo cada tanto para eliminar reglas contradictorias: si dos se contradicen, Claude puede elegir cualquiera.

Instalar con criterio de seguridad

Un comando que descarga un script de internet y lo ejecuta al instante merece un párrafo aparte en una comunidad de seguridad. curl … | bash es el método documentado por Anthropic y funciona, pero ejecuta código que no revisaste: toda la confianza descansa en el dominio y en su certificado TLS.

Hay tres caminos razonables, según cuánto quieras verificar:

1. Usar un gestor de paquetesHomebrew en macOS, WinGet en Windows y los repositorios apt, dnf y apk en Linux verifican firmas con la infraestructura del propio gestor. El costo es que ninguno se actualiza solo.
2. Descargar el script y leerlo antes de ejecutarloGuardarlo en un archivo, revisarlo y recién después correrlo. Es el término medio entre comodidad y control.
3. Verificar la firma GPG del manifiestoCada versión publica un manifest.json con las sumas SHA256 de todos los binarios, firmado con una clave GPG de Anthropic. Verificar la firma del manifiesto valida transitivamente cada binario que lista. Hay firmas disponibles desde la versión 2.1.89.

La huella digital de la clave de firma tiene que coincidir exactamente con:

31DD DE24 DDFA B679 F42D  7BD2 BAA9 29FF 1A7E CACE

Los binarios llevan además firma nativa de plataforma donde la hay: en macOS están firmados por «Anthropic PBC» y notarizados por Apple, verificables con codesign --verify --verbose ./claude; en Windows están firmados por «Anthropic, PBC» y se comprueban con Get-AuthenticodeSignature .\claude.exe. Los binarios de Linux no se firman individualmente: ahí la verificación pasa por el manifiesto o por el gestor de paquetes.

Vale también el consejo general: descargá siempre desde el dominio oficial. El blog de Underc0de documentó el caso de extensiones maliciosas dirigidas a IDEs con IA basados en VS Code y varias campañas de paquetes maliciosos en npm y PyPI que roban credenciales. El ecosistema de herramientas de IA para programar es un objetivo activo, y los nombres parecidos son el vector más barato.

Actualizar y desinstalar

Actualizaciones

Las instalaciones nativas se actualizan solas en segundo plano: Claude Code comprueba si hay versiones nuevas al arrancar y cada tanto mientras corre, las descarga e instala, y la nueva versión toma efecto en el siguiente inicio. Las instalaciones por Homebrew, WinGet, apt, dnf y apk no se actualizan solas.

Para forzar una actualización sin esperar:

claude update

Se puede elegir el canal con el ajuste autoUpdatesChannel en settings.json: "latest" —el valor por defecto— entrega las novedades apenas salen, y "stable" usa una versión de aproximadamente una semana de antigüedad, saltando las que tuvieron regresiones importantes. También se configura desde /config. Para desactivar la actualización automática se define DISABLE_AUTOUPDATER con valor "1" dentro de la clave env.

Desinstalación

Con el instalador nativo, se borran el lanzador y los archivos de versiones:

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Con los gestores de paquetes se desinstala el paquete: brew uninstall --cask claude-code, winget uninstall Anthropic.ClaudeCode, sudo apt remove claude-code o npm uninstall -g @anthropic-ai/claude-code, según corresponda.

La configuración, los permisos guardados, los servidores MCP y el historial de sesiones viven aparte, en ~/.claude y ~/.claude.json. Borrarlos elimina todo eso, así que hacelo solo si querés empezar de cero. Tené en cuenta que la extensión de VS Code, el complemento de JetBrains y la aplicación de escritorio también escriben en ~/.claude: si alguno sigue instalado, la carpeta se vuelve a crear.

Errores frecuentes

«command not found: claude» o «'claude' no se reconoce»

La instalación funcionó, pero el directorio no está en el PATH. El lanzador queda en ~/.local/bin/claude en macOS y Linux, y en %USERPROFILE%\.local\bin\claude.exe en Windows. Lo primero es cerrar y volver a abrir la terminal. Si no alcanza, hay que agregar el directorio a la configuración de tu intérprete —~/.zshrc en macOS, ~/.bashrc en la mayoría de las distribuciones de Linux— y recargarla.

Los errores clásicos de Windows

Casi todos se reducen a haber copiado el comando de otra consola o de otro sistema:

«running scripts is disabled on this system»

Aparece al instalar o ejecutar Claude Code a través de npm en Windows: la política de ejecución de PowerShell bloquea los scripts .ps1 que npm crea para sus comandos. No afecta al instalador de PowerShell, que ejecuta el texto descargado directamente. Se resuelve permitiendo los scripts locales del usuario, llamando a los lanzadores .cmd en lugar de los .ps1, o directamente usando el instalador nativo.

«syntax error near unexpected token '<'» o un error 403

El instalador devolvió una página HTML en lugar del script. Suele ser un proxy o un filtro de red que intercepta el dominio, o que Claude Code no está disponible en tu región. Para descartarlo, comprobá que llegás al servidor de descargas:

curl -sI https://downloads.claude.ai/claude-code-releases/latest

Una línea HTTP/2 200 significa que llegaste. En PowerShell hay que escribir curl.exe -sI, porque curl a secas es un alias que rechaza esos parámetros. Si estás detrás de un proxy corporativo, definí HTTP_PROXY y HTTPS_PROXY antes de instalar.

«This organization has been disabled» con una suscripción activa

Casi siempre es una variable ANTHROPIC_API_KEY vieja que quedó en el perfil de la terminal y que tiene prioridad sobre las credenciales de tu suscripción. Se resuelve quitándola del entorno y borrando la línea export ANTHROPIC_API_KEY=… de ~/.zshrc, ~/.bashrc o ~/.profile. En Windows, revisá el perfil de PowerShell y las variables de entorno de usuario. Dentro de la sesión, /status confirma qué método de autenticación está activo.

El comando «claude» abre la aplicación de escritorio en Windows

Las versiones antiguas de la aplicación de escritorio registran un Claude.exe en el directorio WindowsApps que gana prioridad en el PATH. Se soluciona actualizando la aplicación de escritorio a la última versión.

Varias instalaciones conviviendo

Si el comportamiento es raro o la versión no coincide con la que instalaste, puede haber más de una copia. En macOS y Linux, which -a claude lista todos los binarios que aparecen en el PATH. Una instalación nativa se ve como un enlace simbólico hacia ~/.local/share/claude/versions/.

Preguntas frecuentes

Fuentes

Documentación oficial y material de la comunidad consultados para esta guía. Fecha de consulta: 27 de julio de 2026. Los métodos de instalación y los requisitos cambian con frecuencia: ante cualquier diferencia, la documentación oficial manda.

Documentación oficial

1. Anthropic. Claude Code — Advanced setup. Requisitos de sistema, instalación por plataforma, canales de versión, verificación de firmas y desinstalación.
2. Anthropic. Claude Code — Quickstart. Inicio de sesión, primera sesión y comandos esenciales.
3. Anthropic. Troubleshoot installation and login. Errores de instalación, PATH, red y autenticación.
4. Anthropic. How Claude remembers your project. Archivos CLAUDE.md, ubicaciones y buenas prácticas.
5. Anthropic. Configuración avanzada (documentación en español). Traducción oficial de la página de instalación.
6. Anthropic. Supported countries. Países donde el servicio está disponible.
7. Microsoft. Install WSL. Activación del Subsistema de Windows para Linux.
8. Git. Git for Windows. Descarga oficial.
9. Node.js. Descargas. Necesario solo para la instalación por npm.

Material de la comunidad Underc0de

10. Underc0de, foro. Sección Inteligencia Artificial y BioHacking. Hilos de la comunidad sobre IA.
11. Underc0de, blog. Extensiones maliciosas amenazan IDEs con IA basados en VS Code. Riesgos de la cadena de suministro en herramientas de IA para programar.
12. Underc0de, blog. Detectan paquetes maliciosos en npm y PyPI que roban credenciales.
13. Underc0de, blog. Etiqueta «inteligencia artificial». Cobertura de novedades del sector.