Instalación de Ruby con mise o rbenv y manejo de múltiples versiones

Introducción

Si trabajás con Ruby, seguramente te habrá pasado que diferentes proyectos requieren versiones distintas del lenguaje. Un mismo proyecto puede necesitar Ruby 3.0, mientras que otro funciona mejor con Ruby 3.2. Intentar tener todas las versiones instaladas en el sistema de forma global suele traer problemas de conflictos, fallos en las gems y un entorno de desarrollo inestable.

La solución es usar un version manager: una herramienta que permite tener múltiples versiones de Ruby instaladas en una misma máquina y seleccionar cuál querés usar en cada proyecto. Hoy te guiaré en la instalación de Ruby usando dos de los tools más populares:

• mise – una herramienta moderna y rápida que combina facilidades de uso con un motor de plugins extensible.
• rbenv – el version manager clásico de Ruby, conocido por su simplicidad y amplia adopción.

A lo largo de este artículo, vas a aprender cómo instalar cada herramienta, cómo agregar varias versiones de Ruby y cómo cambiar entre ellas en forma fluida. Además, vas a ver comandos reales junto con la salida que podés esperar, para que puedas copiarlos y pegarlos sin dudas.

Para quién está pensada esta guía

• Desenvolvíos en Ruby y estás cansado de lidiar con problemas de versiones.
• Querés una manera limpia de mantener Ruby 3.1 para un proyecto legacy y Ruby 3.2 para la nueva aplicación.
• Buscás una alternativa moderna (mise) o preferís mantener los tools clásicos (rbenv).

Al final de este artículo, vas a tener un entorno de Ruby completamente funcional y bajo control, con capacidad de cambiar la versión en un santiamén.

Por qué necesitas un version manager

Aislación de proyectos

Cuando tenés múltiples proyectos que dependen de diferentes versiones de Ruby, querés que cada proyecto use su propia versión sin afectar las demás. Sin un version manager, podrías terminar instalando una versión globalmente y luego having que reinstallar o recompilar para cada proyecto, un quebradero de cabeza constante.

Compatibilidad con gems

Muchas gems tienen requisitos estrictos en cuanto a la versión de Ruby. Si intentás ejecutar una gem que necesita Ruby 3.0 en un sistema donde solo tenés Ruby 3.2 globalmente, la gem puede no funcionar o incluso fallar al momento de la instalación.

Mantenimiento del sistema

Los version managers mantienen todo ordenado: las instalaciones están aisladas, podés actualizar una versión sin tocar las demás, y podés limpiar versiones que ya no usás sin riesgo de romper el sistema.

mise vs rbenv: un resumen rápido

Si querés una herramienta moderna que también pueda manejar otros languages (Node, Python), mise es una excelente opción. Si preferís la solución clásica de Ruby con amplia documentación, rbenv es la opción segura.

Instalación de Ruby con mise (el enfoque moderno)

Requisitos previos

mise funciona en Linux, macOS e incluso Windows (WSL). Solo necesitás un shell moderno (bash, zsh, fish) y permisos para escribir en $HOME/.local o /usr/local.

# Verificar la versión de bash (3.2+)
bash --version
# Verificar la versión de zsh (si la usás)
zsh --version

Paso 1: Instalar mise

mise se instala con su script oficial. El comando es seguro y escribe el binario en ~/.local/bin (o /usr/local/bin si tenés permisos de sudo).

# Abrí una nueva terminal o refrescá el shell para que el PATH se actualice
export PATH="$HOME/.local/bin:$PATH"

# Ejecutá el script de instalación (esto es seguro, es código abierto)
curl -fsSL https://mise.jdx.dev/install.sh | bash

Salida esperada (puede variar levemente según el sistema):

Downloading installer...
Installing mise to /home/usuario/.local/bin/mise
Adding /home/usuario/.local/bin to your PATH for this session
Restart your shell or run the following to persist the PATH addition:
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Luego de la instalación, podés verificar:

mise --version
# Expected output:
# mise 2024.4.1

Paso 2: Instalar Ruby con mise

mise puede instalar cualquier versión listada en las releases oficiales de Ruby. Verificá qué versiones están disponibles:

mise ls-remote ruby
# Expected output (excerpt):
# 3.0.0
# 3.0.1
# 3.0.2
# 3.1.0
# ... (muchas más)

Vamos a instalar tres versiones comunes: Ruby 3.0.2, Ruby 3.1.3 y Ruby 3.2.2.

mise install 3.0.2

Salida esperada (vista general):

Installing ruby 3.0.2... (this may take a few minutes)
Downloading ruby-3.0.2.tar.gz from https://github.com/ruby/ruby/releases/download/v3.0.2/ruby-3.0.2.tar.gz
Extracting...
Configuring with options ...
Making... (compiling)
Installing to /home/usuario/.local/share/mise/versions/ruby/3.0.2
# ... (muchos logs de compilación)
Successfully installed ruby-3.0.2

Ahora instalá Ruby 3.1.3:

mise install 3.1.3

Y Ruby 3.2.2:

mise install 3.2.2

Después de las tres instalaciones, podés listar qué versiones tiene mise:

mise list
# Expected output:
# 3.0.2
# 3.1.3
# 3.2.2

Paso 3: Verificar Ruby

Una vez instalada, podés ejecutar mise exec <version> -- ruby --version o usar el helper mise use para cambiar la versión temporalmente.

# Hacer Ruby 3.2.2 el default globalmente (afecta a todas las shells nuevas)
mise use ruby@3.2.2

Ahora verifica la versión de Ruby:

ruby --version
# Expected output:
# ruby 3.2.2p... (el número de build exacto puede variar)

Si abrís una nueva shell y volvéis a correr ruby --version, seguirá mostrando 3.2.2 (el global). Si querés un default por proyecto, podés crear un archivo .ruby-version (mise entiende ese nombre también) dentro de tu proyecto.

Instalación de Ruby con rbenv (el clásico)

Requisitos previos

rbenv funciona mejor en sistemas Unix-like. En macOS podés instalar las herramientas de línea de comando de Xcode (xcode-select --install). En Ubuntu/Debian:

sudo apt update && sudo apt install -y git build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev curl llvm libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

Paso 1: Clonar rbenv y ruby-build

# Crear el directorio donde se clonará rbenv (normalmente $HOME/.rbenv)
git clone https://github.com/rbenv/rbenv.git ~/.rbenv

Luego agregá rbenv al PATH para esta sesión:

cd ~/.rbenv && src/configure && make -C src
sudo mkdir -p /usr/local/share && sudo ln -s ~/.rbenv/plugins/ruby-build /usr/local/share/ruby-build

Ahora agregá rbenv al shell (ejemplo para Bash):

cat >> ~/.bashrc <<'EOF'
export RBENV_ROOT="$HOME/.rbenv"
export PATH="$RBENV_ROOT/bin:$PATH"
eval "$(rbenv init -)"
EOF
source ~/.bashrc

Salida esperada: No se imprime nada (excepto errores si algo falla). Después de esto, podés verificar:

rbenv --version
# Expected output:
# rbenv 1.1.0-45-gb780e79

Paso 2: Instalar ruby-build

git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

Paso 3: Instalar versiones de Ruby

Listá las versiones disponibles:

rbenv install -l
# Expected output (excerpt):
#  3.0.0
#  3.0.1
#  3.0.2
#  3.1.0
#  3.1.1
#  3.1.2
#  3.1.3
#  3.2.0
#  3.2.1
#  3.2.2
#  ...

Ahora instalá las mismas tres versiones que usaste con mise:

rbenv install 3.0.2

Salida esperada (vista general):

Downloading ruby-3.0.2.tar.gz...
=> ruby-3.0.2.tar.gz: 49.81 MiB (52.197.048 bytes)
Compilando ruby-3.0.2...

   * Installing into /home/usuario/.rbenv/versions/3.0.2...
   * Installing header files into /home/usuario/.rbenv/versions/3.0.2/include
   * Installing man pages into /home/usuario/.rbenv/versions/3.0.2/share/man

=> ruby-3.0.2 installed

Repetí para 3.1.3 y 3.2.2:

rbenv install 3.1.3
rbenv install 3.2.2

Después de las instalaciones, lista las versiones:

rbenv versions
# Expected output (excerpt):
#  3.0.2 (set by global)
# * 3.1.3
#  3.2.2

Paso 4: Verificar la versión global

Hacemos que la versión global sea 3.2.2 (la que más usamos):

rbenv global 3.2.2

Ahora verifica:

ruby --version
# Expected output:
# ruby 3.2.2p...

Si abrís una nueva shell, rbenv detectará la versión global.

Gestión diaria de versiones con mise

Listar todas las versiones disponibles

mise ls-remote ruby

Instalar una versión (local)

Supongamos que estás en un proyecto que necesita Ruby 3.1.3. Creá un directorio, cloná el repo y agregá un archivo .ruby-version.

mkdir ~/proyecto-ruby
cd ~/proyecto-ruby

Ahora instalá la versión dentro del directorio:

mise install 3.1.3

Salida esperada (similar a antes):

Installing ruby 3.1.3...
Downloading ruby-3.1.3.tar.gz...
... (compilación) ...
Successfully installed ruby-3.1.3

Crea el archivo .ruby-version:

echo "3.1.3" > .ruby-version

Ahora, dentro del mismo directorio, ruby --version debe mostrar 3.1.3 sin necesidad de un comando explícito.

Cambiar entre versiones

Si ya tenés varias versiones instaladas, podés cambiar rápidamente:

# Para cambiar de forma global (afecta a toda la máquina)
mise use ruby@3.0.2

O para un solo proyecto (lee el archivo .ruby-version):

# No es necesario; mise lo detecta automáticamente si hay un .ruby-version local.

También podés ver qué versión estás usando:

mise current
# Expected output (si .ruby-version está presente):
# local: 3.1.3
# global: 3.2.2

Eliminar una versión (opcional)

mise uninstall 3.0.2
# Expected output:
# Uninstalling ruby-3.0.2...
# Successfully uninstalled ruby-3.0.2

Gestión diaria con rbenv

Listar versiones disponibles

rbenv install -l

Instalar una versión

Dentro de un proyecto:

rbenv install 3.0.2

Salida esperada (vista general):

Downloading ruby-3.0.2.tar.gz...
=> ruby-3.0.2.tar.gz: 49.81 MiB (52.197.048 bytes)
Compilando ruby-3.0.2...

   * Installing into /home/usuario/.rbenv/versions/3.0.2...
   * Installing header files into /home/usuario/.rbenv/versions/3.0.2/include
   * Installing man pages into /home/usuario/.rbenv/versions/3.0.2/share/man

=> ruby-3.0.2 installed

Crear un archivo .rbenv-version

echo "3.1.3" > .rbenv-version

Ahora rbenv lo detectará automáticamente.

Cambiar la versión global o local

# Global (todo el sistema)
rbenv global 3.2.2

# Local (solo este directorio)
rbenv local 3.1.3

Verificá:

rbenv global
# Expected output:
# 3.2.2

ruby --version
# Expected output (si estás en el directorio con .rbenv-version):
# ruby 3.1.3p...

Eliminar una versión

rbenv uninstall 3.0.2

Salida esperada (vista general):

Removing /home/usuario/.rbenv/versions/3.0.2...
   * Removing bin/...
   * Removing lib/...
   * Removing include/...
   * Removing share/...

=> 3.0.2 removed

Flujo de trabajo típico: alternar versiones entre proyectos

Imaginá que tenés tres proyectos:

• legacy-app – necesita Ruby 3.0.2.
• api-v2 – feliz con Ruby 3.1.3.
• frontend – lista para Ruby 3.2.2.

1. Configurar cada proyecto

legacy-app

mkdir ~/projects/legacy-app
cd ~/projects/legacy-app
rbenv init  # si usás rbenv, o mise simplemente
rbenv install 3.0.2
echo "3.0.2" > .rbenv-version

api-v2

mkdir ~/projects/api-v2
cd ~/projects/api-v2
rbenv install 3.1.3
echo "3.1.3" > .rbenv-version

frontend

mkdir ~/projects/frontend
cd ~/projects/frontend
rbenv install 3.2.2
echo "3.2.2" > .rbenv-version

Ahora cada proyecto tiene su propia versión de Ruby.

2. Verificar sin salir del shell

Si estás en una sesión de terminal que ya tiene una versión global de Ruby (digamos 3.2.2), podés forzar un proyecto a usar una versión específica:

cd ~/projects/legacy-app
rbenv local 3.0.2
ruby --version
# Expected output:
# ruby 3.0.2p...

Con mise, el mismo patrón es aún más sencillo:

cd ~/projects/legacy-app
mise use ruby@3.0.2
ruby --version
# Expected output:
# ruby 3.0.2p...

3. Verificar las instalaciones

Asegúrate de que cada versión tenga las gems correctas:

cd ~/projects/legacy-app
bundle install --path vendor/bundle

Repetí el comando bundle install en cada proyecto y vas a ver que cada uno compila las gems con su versión respectiva de Ruby.

Mejores prácticas y errores comunes

1. No uses nunca una versión de Ruby globalmente para todo el sistema – esto anula el propósito del version manager. Mantené una versión global consistente (por ejemplo, la última estable) y dejá que cada proyecto defina su propia versión.

2. Asegurate de que ~/.rbenv/version o ~/.mise/version estén en .gitignore – algunos plugins escriben un archivo version para indicar la versión global; si lo subís a VCS, podés causar conflictos.

3. Actualizá tus tools periódicamente – tanto mise como rbenv tienen lanzamientos frecuentes. Con mise puedes hacer mise self-update. Con rbenv, puedes hacer cd ~/.rbenv && git pull origin master.

4. Evita conflictos de compilación – si tenés múltiples versiones de Ruby instaladas, a veces las flags de compilación (CFLAGS, LDFLAGS) pueden causar warnings. Si ves errores como error: ‘rb_io_t’ has no member named ‘_fileno’, intentá limpiar el directorio de compilación o reinstalá la versión con mise install --force 3.2.2.

5. Cuando agregues nuevas versiones, probá rbenv rehash (rbenv) o mise exec (mise) para asegurarte de que los ejecutables (bundle, rails, etc.) estén en el PATH correcto.

6. Usa rbenv global (rbenv) o mise use (mise) de forma esporádica – no alternates repeatedly dentro de la misma sesión a menos que sea absolutamente necesario. Los cambios frecuentes pueden causar confusión, especialmente si tenés scripts que dependen de un binario específico.

7. Versioná tus archivos .ruby-version o .rbenv-version en el control de versiones – si olvidas crearlos, el equipo que trabaje en el proyecto podría terminar usando una versión global no deseada.

Conclusión

Has recorrido tanto mise (el tool moderno y plugin-friendly) como rbenv (el clásico version manager de Ruby). Ambos te permiten:

• Instalar múltiples versiones de Ruby en una misma máquina.
• Elegir la versión correcta por proyecto sin conflictos.
• Gestionar y eliminar versiones con facilidad.

La elección entre mise y rbenv depende de tus preferencias personales y del resto de tu stack de herramientas. Si también manejas Node, Python o Go, mise te dará un centro de control unificado. Si prefieres una solución de Ruby pura con amplia documentación y soporte, rbenv sigue siendo la opción preferida por muchos.

Ahora podés:

1. Seleccionar mise o rbenv según lo que prefieras.
2. Instalar cualquier versión de Ruby que necesites con un simple mise install <version> o rbenv install <version>.
3. Configurar cada proyecto con un archivo .ruby-version / .rbenv-version para aislamiento.
4. Cambiar entre versiones con mise use o rbenv global/local según el contexto.

El siguiente paso después de dominar el version management es considerar herramientas complementarias como bundler, chruby, o ruby-build (si bien ruby-build está integrado en rbenv ahora). También podrías explorar direnv para cargar automáticamente las versiones de Ruby cuando ingresas a un directorio.

Ahora tenés un entorno de Ruby limpio, potente y bajo control. ¡Feliz coding!