Instalar Gemini CLI en Ubuntu 22.04 24.04 26.04: Guía de Node.js npm y Solución de Problemas

Prerrequisitos

Antes de iniciar la instalación de Gemini CLI en Ubuntu, prepáralo siguiente:

Versión de Ubuntu: 20.04 LTS o más reciente (22.04, 24.04 y 26.04 están totalmente soportadas).
Acceso administrativo: Privilegios de sudo para la gestión de paquetes.
Conexión a Internet: Necesaria para descargar Node.js, paquetes npm y para la autenticación.
Cuenta de Google: Necesaria para el inicio de sesión OAuth y acceder a los modelos Gemini.
Hardware recomendado: Al menos 4 GB de RAM y 2 núcleos de CPU para un rendimiento fluido durante las sesiones interactivas.

Conocimientos básicos asumidos: Sabes cómo abrir una terminal y ejecutar comandos básicos de apt y bash.

Paso计量 1: Actualizar los Paquetes del Sistema

Comienza actualizando la lista de paquetes y mejorando los paquetes existentes para evitar conflictos de dependencias:

sudo apt update && sudo apt upgrade -y

Este paso asegura que tienes las últimas actualizaciones de seguridad e información del repositorio.

Paso计量 2: Instalar Node.js 20 o Superior

Gemini CLI requiere Node.js versión 20 o más reciente. Los repositorios predeterminados de Ubuntu a menudo incluyen versiones más antiguas (por ejemplo, Node 18 en Ubuntu 24.04).

Método Recomendado: Repositorio de NodeSource

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Alternativa: Usar nvm (Node Version Manager)

Para una gestión de versiones más sencilla:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
nvm alias default 20

Verifica la instalación:

node --version
npm --version

Deberías ver una salida similar a v20.x.x para Node.js y una versión de npm correspondiente.

Paso计量 3: Instalar Gemini CLI

Instalación Global (Recomendada para Uso Diario)

npm install -g @google/gemini-cli

Esto hace que el comando gemini esté disponible en todo el sistema.

Prueba Rápida sin Instalación Permanente

Si quieres probarlo primero:

npx @google/gemini-cli

Instalación a Nivel de Usuario (Evitar Problemas de Permisos)

Si encuentras errores de permisos con la instalación global:

mkdir -p ~/.local/bin
npm config set prefix '~/.local'
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @google/gemini-cli

Paso计量 4: Verificar la Instalación

Comprueba que Gemini CLI está correctamente instalado:

gemini --version

La salida esperada muestra la versión actual de Gemini CLI.

Paso计量 5: Iniciar y Autenticar

Ejecuta la CLI por primera vez:

gemini

La herramienta te pedirá que inicies sesión con Google. Se abrirá automáticamente una ventana del navegador. Completa el flujo OAuth y regresa a la terminal.

Después de una autenticación exitosa, se cargará la interfaz interactiva de Gemini CLI. Usa /help para ver los comandos disponibles.

Mejor práctica: Navega a tu directorio de proyecto antes de iniciar:

cd ~/my-project
gemini

Problemas comunes y solución de problemas

'gemini: command not found': Reinicia tu terminal o ejecuta source ~/.bashrc. Verifica tu PATH con echo $PATH.
Permiso denegado durante npm install: Usa el método de instalación a nivel de usuario mencionado anteriormente en lugar de sudo npm.
Error de versión de Node.js: Vuelve a ejecutar la configuración de NodeSource o cambia de versión con nvm. Confirma con node --version.
Fallo de autenticación: Desactiva los bloqueadores de ventanas emergentes del navegador, asegúrate de que las cookies están habilitadas e inténtalo de nuevo. Limpia la caché de npm si es necesario: npm cache clean --force.
Tiempo de espera de red o errores de descarga (ej., ripgrep prebuilt): Asegúrate de tener una conexión a Internet estable. Reintenta la instalación o usa npx como alternativa.
Falta de herramientas de compilación: Instala las dependencias de desarrollo:

sudo apt install -y build-essential python3

Problemas específicos de WSL: Ejecuta los comandos en un terminal estándar de Ubuntu en lugar de WSL si ocurren errores de compilación.

Para obtener más ayuda, consulta el repositorio oficial de GitHub: https://github.com/google-gemini/gemini-cli.

Siguientes pasos

Explora los comandos principales: Escribe /help, /model, o /settings dentro de la CLI.
Usa en proyectos: Pídele a Gemini que explique código, refactorice funciones o genere archivos nuevos con instrucciones en lenguaje natural.
Personaliza: Edita los archivos de configuración en ~/.config/gemini-cli/ para temas, modelos predeterminados y extensiones.
Actualiza regularmente: Ejecuta npm update -g @google/gemini-cli para obtener las últimas mejoras.
Integra herramientas: Experimenta con las extensiones integradas y servidores MCP para flujos de trabajo de agentes avanzados, como integración con git.

Ahora estás listo para usar Gemini CLI como un poderoso asistente de IA para programación directamente en tu terminal de Ubuntu. Comienza con instrucciones simples en una carpeta de proyecto y gradualmente crea tareas más complejas para agentes.

¡Feliz programación con Gemini!