Cómo Instalar Claude Code en Mac y Solucionar Problemas de PATH

Claude Code es una herramienta de línea de comandos que permite a los desarrolladores delegar tareas de programación directamente a Claude desde la terminal. Sin embargo, su instalación en macOS puede presentar algunos desafíos relacionados con la configuración del PATH.

En este artículo te explicaré paso a paso cómo instalarlo correctamente y cómo solucionar los problemas más comunes.

¿Qué es Claude Code?

Claude Code es una herramienta CLI (Command Line Interface) desarrollada por Anthropic que te permite interactuar con Claude directamente desde tu terminal.

Es especialmente útil para desarrolladores que quieren integrar las capacidades de IA de Claude en su flujo de trabajo de desarrollo sin salir del entorno de terminal.

Requisitos Previos

Antes de comenzar, asegúrate de tener instalado:

• macOS (este tutorial está específicamente para Mac)
• Python 3.8 o superior
• pip (el gestor de paquetes de Python)
• Node.js (recomendado para funcionalidades avanzadas)

Paso 1: Instalar Claude Code

El método más sencillo es usar pip o pipx:

pip install claude-code

O si prefieres usar pipx (recomendado para aislar las dependencias):

pipx install claude-code

La instalación normalmente coloca el ejecutable en ~/.local/bin/claude.

Paso 2: Verificar la Instalación

Para confirmar que Claude Code se instaló correctamente en la ubicación esperada, ejecuta:

ls -la ~/.local/bin/claude

Deberías ver algo similar a:

lrwxr-xr-x 1 usuario staff 66 31 ene 09:24 claude -> /Users/usuario/.local/share/claude/versions/2.1.27

Si ves este resultado, significa que Claude Code está instalado correctamente, pero aún no está accesible desde cualquier ubicación en tu terminal.

El Problema del PATH en macOS

Aquí es donde muchos usuarios se encuentran con problemas. Al intentar ejecutar claude en la terminal, recibes el siguiente error:

-bash: claude: command not found

Este error ocurre porque el directorio donde se instaló Claude Code (~/.local/bin) no está incluido en tu variable de entorno PATH. El PATH es una lista de directorios donde el sistema busca ejecutables cuando escribes un comando.

Solución: Configurar el PATH Permanentemente

La solución depende del shell que estés usando en tu Mac. Vamos a identificarlo primero.

Identificar tu Shell

Ejecuta el siguiente comando:

echo $SHELL

Las respuestas más comunes son:

• /bin/bash - Shell Bash (común en versiones antiguas de macOS)
• /bin/zsh - Shell Zsh (predeterminado desde macOS Catalina)

Solución para Bash

Si tu shell es bash (respuesta: /bin/bash), sigue estos pasos:

1. Abrir el archivo de configuración

nano ~/.bash_profile

2. Añadir la ruta al PATH

Ve al final del archivo y añade esta línea:

export PATH="$HOME/.local/bin:$PATH"

Nota importante: Si ya tienes otras líneas de export PATH en el archivo (por ejemplo, para Herd, Python, NVM, etc.), simplemente añade esta nueva línea al final. No borres las configuraciones existentes.

3. Guardar el archivo

En el editor nano:

• Presiona Ctrl + O para guardar
• Presiona Enter para confirmar
• Presiona Ctrl + X para salir

4. Aplicar los cambios

source ~/.bash_profile

Solución para Zsh

Si tu shell es zsh (respuesta: /bin/zsh), el proceso es similar pero con un archivo diferente:

1. Abrir el archivo de configuración

nano ~/.zshrc

2. Añadir la ruta al PATH

export PATH="$HOME/.local/bin:$PATH"

3. Guardar y aplicar cambios

source ~/.zshrc

Verificación Final

Una vez completados estos pasos, es importante verificar que todo funciona correctamente:

1. Cerrar y reabrir la terminal

Este paso es crucial para asegurarte de que los cambios se aplican automáticamente en futuras sesiones.

2. Verificar que el comando está disponible

which claude

Debería mostrar:

/Users/tu_usuario/.local/bin/claude

3. Comprobar la versión instalada

claude --version

Si todo está correcto, verás la versión de Claude Code instalada.

4. Probar el comando desde cualquier directorio

Navega a diferentes carpetas y ejecuta:

cd ~/Documents claude --help cd ~/Desktop claude --help

El comando debería funcionar sin importar en qué directorio te encuentres.

Problemas Comunes y Soluciones

Problema 1: "command not found" después de configurar PATH

Síntoma: Has añadido la línea al archivo de configuración pero sigues viendo el error.

Soluciones:

Verifica que editaste el archivo correcto:

• Para bash: ~/.bash_profile (NO ~/.bashrc)
• Para zsh: ~/.zshrc

Comprueba que no hay errores de sintaxis:

cat ~/.bash_profile # o ~/.zshrc

Busca la línea export PATH="$HOME/.local/bin:$PATH" y asegúrate de que está correctamente escrita.

Recarga el archivo de configuración:

source ~/.bash_profile # o source ~/.zshrc

Cierra TODAS las ventanas de terminal y abre una nueva.

Problema 2: Líneas duplicadas en el archivo de configuración

Síntoma: Tienes múltiples líneas idénticas de export PATH="$HOME/.local/bin:$PATH" en tu archivo.

Solución:

Abre el archivo:

nano ~/.bash_profile

Elimina las líneas duplicadas, dejando solo UNA instancia.

Guarda y recarga:

source ~/.bash_profile

Problema 3: Claude Code instalado en una ubicación diferente

Síntoma: ls -la ~/.local/bin/claude no encuentra el archivo.

Solución:

Busca dónde se instaló realmente:

find ~ -name "claude" -type f 2>/dev/null

Una vez encontrada la ubicación, añade ese directorio específico a tu PATH en lugar de ~/.local/bin.

Problema 4: Permisos de ejecución

Síntoma: El archivo existe pero no se puede ejecutar.

Solución:

chmod +x ~/.local/bin/claude

La instalación de Claude Code en macOS es relativamente sencilla, pero los problemas de configuración del PATH pueden ser frustrantes si no conoces las particularidades del sistema. Espero que este artículo te haya resultado útil. Si tienes alguna duda o has encontrado otro problema durante la instalación ponte en contacto conmigo y te ayudaré a resolverlo.