4. Instalación en Windows, Linux y macOS

Objetivo del tema

Dejar Claude Code instalado en tu sistema operativo con el método más conveniente, completar la autenticación inicial, verificar que el agente responde correctamente y conocer cómo mantenerlo actualizado y resolver los problemas típicos.

4.1 Elegir el método: nativo o npm

Antes de copiar comandos, conviene entender que existen dos familias de instalación con un trade-off claro:

  • Instalador nativo (recomendado): descarga un binario autocontenido e independiente de Node.js. Se actualiza solo, no sufre conflictos de permisos y funciona igual en macOS, Linux y Windows.
  • Instalación vía npm: se integra con tu flujo Node.js existente y permite fijar versiones exactas (@anthropic-ai/claude-code@X.Y.Z), pero requiere Node 18+ y es más sensible a permisos y a cambios de versión de Node.

Si no tienes una razón específica para lo contrario, elige el instalador nativo: es la vía que la documentación oficial privilegia y la que menos fricción produce a largo plazo. Ambas vías conviven sin problema; más adelante veremos cómo diagnosticar cuál está activa.

4.2 Método recomendado: instalador nativo

En macOS, Linux y WSL, un solo comando detecta tu plataforma, descarga el binario adecuado y lo deja disponible como claude:

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

En Windows, desde PowerShell:

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

O desde el símbolo del sistema (CMD):

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

Al terminar, abre una terminal nueva (para refrescar el PATH) y comprueba:

claude --version

El instalador nativo configura además el actualizador automático: a partir de ahora, nuevas versiones llegarán solas mientras trabajas. Si tu política requiere controlar cada versión, más adelante veremos cómo desactivarlo.

¿Es seguro ejecutar un script remoto? El dominio claude.ai es oficial de Anthropic y el instalador solo escribe en tu directorio de usuario, sin pedir privilegios de administrador. Si tu organización prohíbe este método, usa npm o Homebrew según las secciones siguientes.

4.3 Instalación vía npm

Si ya gestionas tus herramientas con Node.js, Claude Code se instala como paquete global:

npm install -g @anthropic-ai/claude-code

Tres advertencias prácticas:

  • Nunca uses sudo: instalar paquetes globales con privilegios de administrador rompe el actualizador automático y genera problemas de permisos difíciles de revertir. Si npm te pide sudo, mejor cambia el prefijo global o migra al instalador nativo.
  • Node 18 o superior: verifica con node --version. Si administras varias versiones con nvm o fnm, recuerda que los paquetes globales dependen de la versión activa: repite la instalación en cada versión que uses.
  • Migración al nativo: si la instalación npm te da problemas de permisos con el actualizador, el propio comando claude install traslada la instalación al esquema nativo sin perder configuración.

4.4 Instalación en macOS y Linux

Homebrew (macOS y Linux):

brew install --cask claude-code

Se integra con brew upgrade y es cómodo para quien ya administra todo con Homebrew. En Linux existen además paquetes comunitarios (por ejemplo en AUR para Arch), mantenidos por terceros y con actualización algo más lenta que el instalador oficial.

Binario manual (cualquier distribución):

Descarga el binario para tu arquitectura desde las releases oficiales, colócalo en una carpeta del PATH (como ~/.local/bin) y dale permisos de ejecución con chmod +x. Es la vía ideal para servidores sin gestores de paquetes o con acceso restringido a internet.

Entornos remotos y contenedores:

Claude Code funciona igual sobre SSH (en un servidor de desarrollo, una VM o un devcontainer de Docker). Instala dentro del entorno remoto con el instalador nativo, y recuerda que las credenciales se guardan por máquina: cada entorno necesita su propia autenticación.

4.5 Instalación en Windows

Windows ofrece dos caminos, ambos con soporte completo:

  • Nativo (PowerShell o CMD): usa el instalador de la sección 4.2. Requiere tener Git for Windows instalado, ya que el agente lo emplea para ejecutar comandos. Verifica con git --version antes de continuar.
  • WSL2: instala Claude Code dentro de Ubuntu usando el comando de Linux (curl ... | bash) y trabaja desde la terminal de WSL. Es la opción preferida para flujos POSIX, scripts de shell y herramientas de compilación tipo Unix. Recuerda del tema 3: clona tus repositorios dentro del sistema de archivos de WSL, no en /mnt/c/.

No instales las dos variantes "por las dudas": elige una, porque dos instalaciones conviviendo generan confusión sobre cuál se ejecuta y cuál se actualiza.

Resumen de métodos de instalación
Método Sistemas Ideal para
Instalador nativo (install.sh / install.ps1) macOS, Linux, Windows, WSL Puesta en marcha rápida, sin Node.js y con auto-actualización.
npm (@anthropic-ai/claude-code) Todos (con Node 18+) Equipos que fijan versiones exactas o ya administran todo con npm.
Homebrew (cask) macOS, Linux Actualizaciones cómodas con brew upgrade.
Binario manual Cualquier Unix Servidores restringidos y despliegues controlados.
WSL2 + instalador de Linux Windows Flujos POSIX y compatibilidad total con herramientas Unix.

4.6 Primer arranque y autenticación

Navega a un proyecto de prueba y abre el agente:

cd /ruta/a/tu/proyecto
claude

El primer arranque realiza tres pasos guiados:

  1. Tema visual: elige entre las opciones claras y oscuras (podrás cambiarla después con /config).
  2. Método de acceso: selecciona Claude account with subscription si usas Pro/Max, o Anthropic Console account si facturarás por API.
  3. Inicio de sesión: se abre el navegador para autenticarte; en el caso de la Console, la clave queda registrada de forma segura.

Alternativas para entornos sin navegador (SSH, CI): exporta la clave como variable de entorno antes de arrancar, o genera un token de larga duración desde una máquina con navegador usando claude setup-token:

export ANTHROPIC_API_KEY="sk-ant-..."   # alternativa válida en cualquier entorno

Las credenciales y la configuración global se guardan en tu directorio de usuario (~/.claude/ y ~/.claude.json), nunca dentro del proyecto. Nunca subas esos archivos a repositorios.

Si el navegador no se abre automáticamente (SSH, contenedores), Claude Code muestra una URL para copiar en cualquier navegador y luego devuelve el código de verificación a la terminal. La autenticación puede completarse desde el teléfono sin problema.

4.7 Comprobaciones esenciales

Comandos iniciales de verificación
Comando Propósito Señal de éxito
claude --version Confirma que el binario está instalado y accesible. Imprime el número de versión sin errores.
claude doctor Diagnóstico integral: instalación, actualizador, permisos y conexión. Reporta el tipo de instalación y su estado como saludable.
claude -p "Di hola" Prueba no interactiva de la conexión con el modelo. El modelo responde en la terminal.
/status (sesión interactiva) Revisa versión, cuenta, modelo activo y estado de la API. Muestra tu suscripción o clave y el modelo configurado.
/help (sesión interactiva) Lista los comandos slash disponibles. Incluye /init, /model, /config, entre otros.

claude doctor merece una mención especial: es el primer comando al que recurrir ante cualquier comportamiento extraño, porque distingue si corres un binario nativo o una instalación npm, verifica que el actualizador funcione y detecta instalaciones duplicadas o corruptas.

4.8 Actualizar y desinstalar

  • Actualización automática: activada por defecto en la instalación nativa; el binario se renueva en segundo plano y la nueva versión entra en vigor en el próximo arranque.
  • Actualización manual: claude update fuerza la búsqueda de la última versión. Con Homebrew, usa brew upgrade; con npm, npm install -g @anthropic-ai/claude-code@latest.
  • Desactivar el auto-actualizador: exporta DISABLE_AUTOUPDATER=1 (por ejemplo en entornos regulados donde cada versión se aprueba antes). Conviene entonces actualizar manualmente con disciplina.
  • Desinstalar: npm uninstall -g @anthropic-ai/claude-code, brew uninstall --cask claude-code, o elimina el binario si fue manual. La configuración personal queda en ~/.claude/; bórrala si quieres empezar de cero.

4.9 Solución de problemas frecuentes

  • "Comando no encontrado" tras instalar: la carpeta del binario no está en el PATH. Abre una terminal nueva o agrega la ruta (~/.local/bin en Linux) al archivo de configuración de tu shell.
  • claude doctor reporta dos instalaciones: desinstala la que no uses (npm o nativa) para evitar que se ejecuten versiones distintas según el contexto.
  • El actualizador falla con npm: síntoma típico de permisos de directorios globales. Solución limpia: claude install para migrar al esquema nativo.
  • Errores de red o proxy corporativo: exporta HTTPS_PROXY/HTTP_PROXY antes de arrancar y confirma con tu área de redes el acceso a api.anthropic.com.
  • En Windows falla la ejecución de comandos: falta Git for Windows (nativo) o estás mezclando entornos: usa la terminal de WSL si instalaste dentro de WSL.
  • Node demasiado antiguo (vía npm): actualiza a Node 18+ o migra al instalador nativo, que no depende de Node.

Conclusión: con el binario instalado, la autenticación completada y claude doctor reportando todo saludable, Claude Code está listo para trabajar. En el próximo tema profundizaremos en las cuentas, los modelos disponibles y cómo elegir el más conveniente para cada tarea.

Retornar