PTENES
MÓDULO 2.1

⚙️ Instalar Claude Code

Requisitos del sistema, instalación mediante npm o Bun, verificación, actualización y diagnóstico de los errores más comunes en macOS, Linux y Windows.

6
Temas
45
Minutos
Básico
Nivel
Práctica
Tipo
1

🖥️ Requisitos del sistema

Antes de empezar, confirma que tu entorno tenga lo necesario. Node.js v18+ es el único requisito obligatorio — todo lo demás es opcional, pero recomendado.

✓ Entorno ideal

  • ✓Node.js v18 o superior (se recomienda LTS)
  • ✓npm v9+ (viene con Node.js) o Bun v1+
  • ✓Terminal con soporte para colores (iTerm2, Warp, Windows Terminal)
  • ✓Acceso a internet para la autenticación OAuth
  • ✓macOS 12+, Ubuntu 20.04+ o WSL2 en Windows

✗ Problemas comunes

  • ✗Node.js v16 o anterior: la instalación falla
  • ✗Windows nativo (cmd/PowerShell sin WSL2) — compatibilidad limitada
  • ✗npm instalado con sudo en Linux — permisos dañados
  • ✗Red corporativa con proxy sin configurar
  • ✗Disco lleno — la instalación de paquetes falla silenciosamente

Verificar las versiones antes de instalar

# Verificar Node.js
node -v
# Output esperado: v18.x.x ou superior

# Verificar npm
npm -v
# Output esperado: 9.x.x ou superior

# Alternativa: verificar Bun
bun -v
# Output esperado: 1.x.x

# Se Node.js não estiver instalado (macOS com Homebrew):
brew install node

# Se Node.js não estiver instalado (Ubuntu/Debian):
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

💡 Consejo: usa nvm para gestionar versiones

O nvm (Node Version Manager) permite instalar y cambiar entre versiones de Node.js sin conflictos. Ideal para quienes trabajan en varios proyectos. Instálalo con curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash y usa nvm install --lts a la versión LTS más reciente.

2

📦 Instalación con npm (y Bun)

La instalación es un solo comando. La flag -g instala globalmente — el binario claude estará disponible en cualquier directorio del sistema.

1

Instalar mediante npm

El método estándar y más confiable

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

Alternativa: instalar con Bun

Más rápido, ideal si ya usas Bun en el proyecto

bun install -g @anthropic-ai/claude-code
3

Esperar a que termine

La instalación tarda entre 30 y 90 segundos, según la red.

# Output esperado durante instalação:
added 247 packages in 45s
+ @anthropic-ai/claude-code@1.x.x
4

Verificar la instalación

Confirmar que el binario está en el PATH

claude --version
# Output: Claude Code 1.x.x

which claude
# Output: /usr/local/bin/claude (ou similar)
Terminal tu shell npm install -g descarga paquete /usr/local/bin binario global $ claude listo ✓
3

✅ Verificación y pruebas

Después de instalarlo, tres comandos confirman que todo está correcto. Ejecútalos en orden: prueban la instalación, el PATH y el funcionamiento básico.

Lista de verificación posterior a la instalación

# 1. Versão instalada
claude --version
# ✓ Claude Code 1.x.x

# 2. Caminho do binário
which claude
# ✓ /usr/local/bin/claude
# ou: /home/user/.local/bin/claude (Linux com nvm)

# 3. Help básico (confirma binário funcional)
claude --help
# ✓ Lista de flags e subcomandos

# 4. Se 'claude' não for encontrado:
# Verificar se ~/.npm/bin está no PATH
echo $PATH | grep npm

# Adicionar ao .bashrc ou .zshrc se necessário:
export PATH="$HOME/.npm/bin:$PATH"

📊 Qué esperar

  • claude --version → imprime la versión semántica (ej.: 1.2.3)
  • which claude → muestra la ruta absoluta del binario
  • claude --help → lista las flags: --print, --resume, --version, --model
  • claude (sin flags) → abre el REPL interactivo o inicia la autenticación
4

🔄 Actualizando Claude Code

Claude Code recibe actualizaciones frecuentes. Las nuevas versiones traen compatibilidad con modelos más recientes, correcciones de bugs y funcionalidades. Actualizar lleva menos de 1 minuto.

💡 Cuándo actualizar

Actualízalo siempre que: aparezca un mensaje de versión desactualizada en la terminal, Anthropic lance un modelo nuevo (Claude 4, etc.) o haya una función que quieras y no esté disponible en tu versión.

Comandos de actualización

# Atualizar via npm
npm update -g @anthropic-ai/claude-code

# Ou reinstalar para garantir última versão
npm install -g @anthropic-ai/claude-code@latest

# Atualizar via Bun
bun update -g @anthropic-ai/claude-code

# Verificar versão atual vs mais recente
npm outdated -g @anthropic-ai/claude-code

# Verificar versão após atualização
claude --version

✓ Buenas prácticas de actualización

  • ✓Actualizar semanalmente en proyectos activos
  • ✓Leer el changelog antes de actualizar en producción
  • ✓Probar en desarrollo antes de actualizar el entorno de CI

✗ Evitar

  • ✗Actualizar durante una sesión activa importante
  • ✗Fijar una versión antigua sin justificación
  • ✗Ignorar los breaking changes en el changelog
5

🖱️ Guía por sistema operativo

Cada OS tiene particularidades de instalación. macOS y Linux son compatibles de forma nativa. Windows funciona mejor con WSL2.

🍎 macOS

# vía Homebrew:

brew install node

# instalar Claude Code:

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

Sin problemas de PATH con Homebrew. La mejor experiencia en general.

🐧 Linux

# vía nvm (recomendado):

nvm install --lts

nvm use --lts

# instalar:

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

Evita apt install nodejs: suele ser una versión antigua.

🪟 Windows (WSL2)

# instalar WSL2:

wsl --install

# dentro de WSL2 (Ubuntu):

nvm install --lts

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

Windows Terminal + WSL2 = una experiencia casi idéntica a la de Linux.

💡 Consejo: Windows Terminal es obligatorio

Si usas Windows, instala el Windows Terminal (gratuito en Microsoft Store). cmd.exe y el PowerShell antiguo no muestran correctamente los colores ni la interfaz de Claude Code. Con Windows Terminal + WSL2, la experiencia es completa.

6

🔧 Diagnóstico: errores comunes

Los 5 errores más frecuentes durante la instalación tienen soluciones directas. Lee el error en la terminal, identifica el tipo y aplica la corrección.

EACCES: permiso denegado

npm no tiene permiso para escribir en la carpeta global

# Solução 1: configurar npm para usar diretório do usuário
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Solução 2: usar nvm (recomendado — evita sudo)
nvm install --lts && npm i -g @anthropic-ai/claude-code

command not found: claude

Instalación correcta, pero PATH no incluye la carpeta global de npm

# Encontrar onde o npm instala globalmente
npm config get prefix
# Ex: /home/user/.npm-global

# Adicionar ao PATH (substituir pelo caminho real)
export PATH="/home/user/.npm-global/bin:$PATH"

# Persistir no .bashrc ou .zshrc
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc

engine "node" unsupported / ENOTSUP

Versión incompatible de Node.js (v16 o inferior)

# Atualizar Node.js com nvm
nvm install 20  # LTS atual
nvm use 20
nvm alias default 20

# Verificar e reinstalar
node -v  # deve mostrar v20.x.x
npm install -g @anthropic-ai/claude-code

⚠️ Nunca uses sudo con npm install -g

Ejecutar sudo npm install -g corrige el EACCES inmediato, pero crea problemas mayores: archivos con ownership de root, conflictos en futuras actualizaciones y riesgos de seguridad. Usa nvm o configura la carpeta global de npm como se indicó arriba.

✅ Resumen del Módulo 2.1

✓
Node.js v18+ es el único requisito obligatorio
✓
npm install -g @anthropic-ai/claude-code — el comando de instalación
✓
claude --version confirma que la instalación se realizó correctamente
✓
¿EACCES? Usa nvm, nunca sudo
✓
¿Windows? WSL2 + Windows Terminal es la combinación adecuada

Siguiente módulo:

2.2 — Autenticación y primer uso: ejecutar claude, inicio de sesión, API key vs. suscripción y tus primeros comandos reales.

← Volver a la ruta 2 Siguiente módulo →