Cómo instalar Claude Code paso a paso (macOS, Windows y Linux)

Para instalar Claude Code basta un comando: curl -fsSL https://claude.ai/install.sh | bash en macOS, Linux o WSL, o irm https://claude.ai/install.ps1 | iex en PowerShell de Windows. Después abres tu proyecto en la terminal, escribes claude e inicias sesión con una cuenta de pago de Claude o de la Claude Console. En esta guía verás cada paso, las alternativas (Homebrew, WinGet, npm) y cómo resolver los errores más comunes.

Probamos la instalación nativa y la vía npm en macOS el 4 de noviembre de 2026 con la versión 2.1.318. Los comandos de Windows y Linux están copiados de la documentación oficial de instalación de esa misma fecha. Si tu equipo quiere ir más allá de la instalación y usar IA en sus propios sistemas, en Adelmi trabajamos en desarrollo de software con inteligencia artificial.

Qué es Claude Code y qué necesitas antes de instalarlo

Claude Code es el asistente de programación de Anthropic que trabaja en tu terminal: lee el código de tu proyecto, propone cambios, edita archivos y ejecuta comandos, siempre pidiendo permiso según el modo que elijas.

Antes de instalar Claude Code, revisa tres cosas.

Una cuenta con acceso. La documentación indica que Claude Code requiere una cuenta Pro, Max, Ultra, Team, Enterprise o de la Claude Console; el plan gratuito de claude.ai no lo incluye. Las empresas también pueden usarlo a través de Amazon Bedrock, Google Cloud (Agent Platform, antes Vertex AI) o Microsoft Foundry (autenticación).

Un sistema compatible. Según la página de requisitos:

Node.js solo si usas npm. El instalador nativo no necesita Node.js. La vía npm pide Node.js 22 o posterior.

Instalar Claude Code en macOS, Linux y WSL

El instalador nativo es el método que la documentación marca como recomendado. Se instala en tu carpeta de usuario (no necesitas sudo) y se actualiza solo en segundo plano.

1. Ejecuta el instalador

   Abre la terminal y ejecuta:

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

   No lo ejecutes con sudo: el script se niega, porque instalaría Claude Code en la carpeta del usuario root y luego tu terminal no encontraría el comando.

2. Comprueba la versión

   claude --version

   En nuestra prueba respondió 2.1.318 (Claude Code). Si la terminal dice que no encuentra claude, abre una ventana nueva o revisa la sección de errores más abajo.

En WSL (el Linux de Windows), instala y abre claude dentro de la terminal de WSL, no desde PowerShell ni CMD. Usa WSL 2: WSL 1 no es compatible con el aislamiento de comandos (sandbox).

En Alpine Linux hay pasos previos: instalar bash, curl, libgcc, libstdc++ y ripgrep, y configurar la variable USE_BUILTIN_RIPGREP en "0". Están en la documentación de requisitos.

Instalar Claude Code en Windows

En Windows tienes dos terminales posibles, y cada una usa un comando distinto. No necesitas ejecutarlas como administrador.

En PowerShell:

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

En CMD (símbolo del sistema):

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

Si pegas el comando de PowerShell en CMD, verás 'irm' is not recognized; si pegas el de CMD en PowerShell, verás The token '&&' is not a valid statement separator. En los dos casos el problema es la terminal, no la instalación.

Canales de actualización: latest y stable

La instalación nativa se actualiza sola. Hay dos canales:

• latest (predeterminado): recibes cada versión en cuanto sale.
• stable: versiones con alrededor de una semana de antigüedad, que omiten las que tuvieron regresiones importantes.

Puedes instalar directamente el canal estable:

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

O cambiarlo después desde Claude Code con /config (opción Auto-update channel), o en el archivo de configuración settings.json:

{
  "autoUpdatesChannel": "stable"
}

Para actualizar a mano, usa claude update. Para revisar la instalación, claude doctor. Si tu empresa necesita congelar versiones, la variable DISABLE_AUTOUPDATER detiene la búsqueda automática de actualizaciones, y DISABLE_UPDATES bloquea cualquier actualización, incluidas las manuales.

Otras formas de instalar Claude Code: Homebrew, WinGet y npm

Si tu equipo ya administra el software con un gestor de paquetes, la documentación oficial lista estas alternativas. Las instalaciones con Homebrew, WinGet y los gestores de paquetes de Linux (apt, dnf, apk) no se actualizan solas: las actualizas con el mismo gestor. Una instalación con npm sí se actualiza sola, y el comando de la tabla sirve para hacerlo a mano.

El cask claude-code de Homebrew sigue el canal estable; claude-code@latest sigue el canal latest. También hay repositorios firmados para apt, dnf y apk, con los comandos completos en la página de instalación.

Con npm, nunca uses sudo npm install -g: la documentación lo desaconseja de forma explícita. Probamos la vía npm con Node.js 22.21.1 y npm 10.9.4, y obtuvimos la misma versión 2.1.318.

Primer uso: abre Claude Code en tu proyecto

Con Claude Code instalado, el flujo de la guía rápida oficial es este:

1. Entra a la carpeta del proyecto y abre Claude Code

   cd /ruta/a/tu/proyecto
   claude

   La primera vez se abre el navegador para iniciar sesión. Si no se abre (por ejemplo, en WSL o por SSH), presiona c para copiar el enlace y pégalo en tu navegador.

2. Haz una primera pregunta

   Escribe, por ejemplo, what does this project do? o la misma pregunta en español. Claude Code lee los archivos necesarios y te responde sin modificar nada.

3. Crea el archivo CLAUDE.md con /init

   El comando /init genera un archivo CLAUDE.md con lo que Claude Code entiende de tu proyecto: cómo se compila, cómo se prueba y qué convenciones sigue. Claude lo lee en cada sesión. Si ya existe, /init sugiere mejoras en lugar de sobrescribirlo (documentación de CLAUDE.md).

Otros comandos útiles: /help lista los comandos, /resume retoma una conversación anterior, /clear empieza de cero y /exit sale. Si Claude Code te pide aprobar un cambio, elige Yes; Shift+Tab cambia el modo de permisos. Cuando quieras conectarlo con otras herramientas, sigue la guía para conectar un servidor MCP a Claude Code.

Errores comunes al instalar Claude Code

Estos son los errores que más aparecen, con la solución de la guía oficial de problemas de instalación.

command not found: claude (macOS/Linux) o 'claude' is not recognized (Windows). La carpeta ~/.local/bin no está en tu PATH. El propio instalador lo avisa al terminar. En zsh (la terminal predeterminada de macOS):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

En Bash usa ~/.bashrc (Linux) o ~/.bash_profile (macOS). En Windows, agrega %USERPROFILE%\.local\bin a la variable PATH de tu usuario y abre una terminal nueva.

syntax error near unexpected token '<' o un error 403 de curl. El servidor devolvió una página web en lugar del script, por ejemplo por un proxy corporativo o porque el servicio no está disponible en tu país. Revisa la red antes de reintentar.

EACCES: permission denied con npm. Cambia al instalador nativo, que no necesita permisos de administrador.

Exec format error en WSL. Estás en WSL 1. Pasa la distribución a WSL 2 con wsl --set-version <DistroName> 2.

Auto-update failed. Ejecuta claude update en tu terminal y lee el error que imprime; búscalo en la guía oficial de problemas de instalación. claude doctor solo muestra la fecha del fallo, no la causa.

Claude Code en empresas: permisos y buenas prácticas

Instalar Claude Code en el equipo de un desarrollador es rápido; usarlo en una empresa pide algunas reglas.

• Elige el modo de permisos. Desde la versión 2.1.283, las sesiones en la terminal empiezan en modo auto: Claude Code ejecuta las acciones y un segundo modelo las revisa en segundo plano. El modo Manual (valor default en la configuración) pregunta antes de editar archivos o ejecutar comandos; acceptEdits deja editar archivos; plan lee y propone. Con permissions.defaultMode en la configuración eliges el modo con el que empieza cada sesión. El modo bypassPermissions (que lo permite todo) está pensado solo para contenedores o máquinas virtuales aisladas (modos de permisos).
• Define reglas compartidas. El archivo .claude/settings.json del repositorio fija qué comandos se permiten, se preguntan o se bloquean para todo el equipo; la configuración administrada (managed settings) permite imponerlas desde TI (configuración).
• Activa el aislamiento cuando ejecute comandos. En macOS, Linux y WSL 2, /sandbox limita los archivos y los dominios a los que pueden acceder los comandos que ejecuta Claude Code.
• Mantén los secretos fuera. No pongas claves ni contraseñas en CLAUDE.md, que normalmente se guarda en el repositorio.
• Revisa todo antes de publicar. Claude Code acelera el trabajo, pero cada cambio pasa por revisión de código y pruebas, igual que el de cualquier persona del equipo.

Si quieres llevar la IA más allá del editor (asistentes con los datos de tu empresa, automatizaciones o agentes conectados a tus sistemas), revisa cómo trabajamos la inteligencia artificial para empresas y escríbenos para una primera reunión.