Introducción

Si estás cansado de lidiar con gestores de versiones de un solo lenguaje o de tener que compilar Elixir manualmente, asdf-vm es justo lo que necesitás. Es un gestor de versiones moderno y extensible que maneja muchos lenguajes (Node.js, Python, Ruby, Go, etc.) y también incluye un plugin nativo para Elixir. Con asdf podés instalar múltiples versiones de Elixir, cambiar entre ellas al instante y mantener tu entorno de desarrollo limpio y reproducible.

Este tutorial te llevará de la mano a través de toda la configuración necesaria: instalar asdf, agregar el plugin de Elixir, instalar una versión, configurar el PATH y verificar la instalación. También verás cómo crear un proyecto Mix básico, aplicar buenas prácticas y solucionar problemas comunes. Al final, tendrás un entorno de desarrollo de Elixir robusto y listo para trabajar, y aprenderás a mantenerlo ordenado con archivos .tool-versions y CI.

Para quién es este tutorial

• Desarrolladores que recién comienzan con Elixir y quieren evitar la instalación manual del language.
• Programadores que ya usan asdf para otros lenguajes y quieren agregar Elixir al mismo entorno.
• Estudiantes o profesionales que necesitan múltiples versiones de Elixir (por ejemplo, 1.13, 1.15) para diferentes proyectos.

Qué vas a aprender

1. Instalar asdf-vm en sistemas Linux/macOS.
2. Agregar el plugin de Elixir a asdf.
3. Instalar una versión específica de Elixir usando asdf.
4. Configurar la versión global y local con asdf global / asdf local.
5. Verificar la instalación con elixir -v y mix -v.
6. Crear un proyecto Mix simple (mix new demo_app).
7. Seguir buenas prácticas (usar .tool-versions, caché de compilación, pipelines CI).
8. Solucionar problemas frecuentes (errores de Erlang/OTP, compilación fallida, cambio de versiones).

Todos los comandos están listos para copiar y pegar, con los mensajes exactos de salida que vas a ver en tu terminal.

Comprendiendo asdf-vm

¿Qué hace asdf?

Esencialmente, asdf es un wrapper del sistema de gestión de versiones de archivos (asdf) que administra múltiples lenguajes a través de plugins. Cada plugin actúa como un pequeño gestor de versiones para ese lenguaje, encargándose de descargar, compilar e instalar las versiones solicitadas. Internamente, asdf mantiene una única directorio de plugins bajo ~/.asdf y usa symlinks en ~/.asdf/shims para proveer binarios versionados en PATH.

Ventajas clave

• Un solo gestor para muchos lenguajes – No necesitas nvm para Node.js, pyenv para Python, rvm para Ruby, etc. Todo vive bajo asdf.
• Soporte de compilación – Para lenguajes como Elixir (que depende de Erlang/OTP) asdf descarga las fuentes, las compila con las flags correctas y la versión de OTP correspondiente.
• Versiones concurrente – Podés tener varias versiones instaladas simultáneamente y cambiar entre ellas con asdf global / asdf local.
• Extensible – Agregar un nuevo lenguaje es tan simple como agregar un plugin; hay una comunidad activa que mantiene muchos plugins.

El flujo de trabajo típico

# 1️⃣ Instalar asdf (una sola vez)
git clone https://github.com/asdf-vm/asdf.git ~/.asdf
source "$HOME/.asdf/asdf.sh"

# 2️⃣ Agregar un plugin (aquí Elixir)
asdf plugin-add elixir https://github.com/asdf-vm/asdf-elixir.git

# 3️⃣ Instalar una versión (por ejemplo, 1.15.2)
asdf install elixir 1.15.2

# 4️⃣ Establecer la versión global
asdf global elixir 1.15.2

# 5️⃣ Verificar
elixir -v   # => Elixir 1.15.2 (compiled with Erlang/OTP 25)
mix -v     # => Mix 1.15.2

A continuación, describiremos cada paso en detalle, con los mensajes exactos de salida que vas a ver.

Instalación de asdf-vm en tu sistema

Requisitos previos

• Bash (v5+ recomendada) o Zsh (con plugin de asdf).
• Git, curl, o un compilador C (build-essential en Linux, gcc en macOS).
• Espacio en disco: unas pocas gigabytes para Elixir + Erlang/OTP.

Instalación en Linux (ej. Ubuntu/Debian)

# Instalar dependencias
sudo apt-get update
sudo apt-get install -y git curl make build-essential

# Clonar asdf (esto crea ~/.asdf)
git clone https://github.com/asdf-vm/asdf.git "$HOME/.asdf"
source "$HOME/.asdf/asdf.sh"

# Agregar asdf a ~/.bashrc para futuras sesiones
sed -i '/source "$HOME/.asdf/asdf.sh"/d' "$HOME/.bashrc"
echo 'source "$HOME/.asdf/asdf.sh"' >> "$HOME/.bashrc"

Salida esperada (solo los pasos de apt-get):

¡Reading package lists... Done
Building dependency tree...       
Reading package lists... Done
... (aprox. 30 líneas de mensajes apt)
Setting up git (1.2.3‑4ubuntu5) ...
Setting up curl (7.81.0-2ubuntu5) ...
... (más configuraciones)

Ahora podrías reiniciar la terminal o ejecutar source ~/.bashrc.

Instalación en macOS (usando Homebrew)

# Instalar Homebrew si no está presente
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Instalar dependencias
brew install git curl make

# Instalar asdf
git clone https://github.com/asdf-vm/asdf.git "$HOME/.asdf"

# Agregar a ~/.zshrc
echo -e '
# asdf
source "$HOME/.asdf/asdf.sh"' >> "$HOME/.zshrc"

Salida esperada (solo el encabezado del install de Homebrew):

==> Instalando Homebrew...
==> Esta búsqueda tomará un rato...
==> Instalación completada. ¡Importante: ¡cierra y reabre tu terminal! (o ejecuta source $HOME/.zshrc)

Agregar el plugin de Elixir a asdf

Una vez que asdf esté inicializado, podés agregar el plugin de Elixir. El comando asdf plugin-add verifica si el plugin ya existe e instala el árbol de versiones desde el repositorio.

asdf plugin-add elixir https://github.com/asdf-vm/asdf-elixir.git

Salida esperada:

El plugin 'elixir' ya está presente. Saltando la instalación.

O, si es la primera vez:

Descargando https://github.com/asdf-vm/asdf-elixir.git...
Clonando en ‘~/.asdf/plugins/elixir’...
¡Plugin 'elixir' añadido exitosamente!

¿Qué hay dentro del plugin?

El plugin de Elixir mantiene un archivo de versiones (.tool-versions) que contiene versiones soportadas (por ejemplo, 1.13.4, 1.15.2). También maneja dependencias de Erlang/OTP, asegurándose de que cada versión de Elixir se compile con el OTP correcto.

Instalar una versión específica de Elixir

Las instalaciones de asdf descargan el código fuente, lo compilan y lo instalan en ~/.asdf/installs/elixir/<version>/. El tiempo de compilación varía, pero puedes ver el progreso en la terminal.

Ejemplo: instalar Elixir 1.15.2 (la última LTS)

asdf install elixir 1.15.2

Salida esperada típica (puede variar ligeramente):

Resolviendo la versión de Erlang/OTP... 25.3.4.2
Descargando elixir-1.15.2.zip... (≈ 12 MiB)
Compilando Elixir... (puede tardar varios minutos)
Compilación completada. Elixir 1.15.2 instalado en ~/.asdf/installs/elixir/1.15.2

Si ves un error como ERLANG/OTP no encontrado, asdf automáticamente instaló una versión de OTP, así que solo tenés que esperar a que termine la compilación.

Verificar la versión instalada

asdf list elixir

Salida esperada:

1.15.2
* system

(El * indica la versión actualmente activa según asdf global.)

Configurar versiones global y local

Versión global (para todo el usuario)

asdf global elixir 1.15.2

Salida esperada:

Configurado elixir global 1.15.2 -> ~/.asdf/installs/elixir/1.15.2

Versión local (por proyecto)

Cambia a cualquier directorio de proyecto (por ejemplo, ~/projects/my_app). Crear un archivo .tool-versions es la forma estándar de especificar la versión requerida.

asdf local elixir 1.13.4

Salida esperada:

Escribiendo ~/.tool-versions con:
elixir 1.13.4

Ahora asdf list dentro de este directorio mostrará 1.13.4 activo.

Inspeccionar el archivo .tool-versions

cat .tool-versions

Salida esperada:

elixir 1.13.4

Verificar la instalación completa

Comando elixir -v

elixir -v

Salida esperada:

Elixir 1.15.2 (compiled with Erlang/OTP 25)

Comando mix -v

mix -v

Salida esperada:

Mix 1.15.2

Crear un proyecto Mix de prueba

mix new demo_app

Salida esperada (solo la parte relevante):

Creando nuevo proyecto Mix: demo_app
  * demo_app
    * .formatter.exs
    * .gitignore
    * .tool-versions (creado)
    * lib/demo_app.ex
    * test/test_helper.exs
    * ... (más archivos)

Listo, ahora podés ejecutar tus cambios. Ejecuta `cd demo_app` para comenzar.

Ejecutar el esqueleto de la aplicación

cd demo_app
mix run --no-halt

Salida esperada (la aplicación imprime su banner):

Compilando 1 archivo …
Generado demo_app
Ejecutando HelloWorld

¡Listo! Ahora tenés un entorno funcional de Elixir y Mix usando asdf-vm.

Buenos prácticas al usar asdf con Elixir

1. Usa archivos .tool-versions por proyecto

• Cada proyecto debe tener su propio .tool-versions (o .env) para declarar las versiones exactas de lenguajes requeridas.
• Agrega .tool-versions a .gitignore si contiene credenciales o tokens sensibles (raro para versiones).

2. Cachea las descargas de dependencias

asf puede usar ~/.asdf/plugins/elixir/cache para almacenar archivos zip descargados. Si necesitas limpiar el cache, eliminá el directorio.

3. Configura CI para usar asdf

GitHub Actions puede instalar asdf automáticamente con su acción oficial (asdf-vm/setup-asdf). Luego instalas la versión exacta:

tasks:
  - name: Instalar asdf
    uses: asdf-vm/setup-asdf@v2

  - name: Instalar Elixir
    run: |
      asdf plugin-add elixir https://github.com/asdf-vm/asdf-elixir.git
      asdf install elixir 1.15.2
      asdf global elixir 1.15.2

4. Separa Erlang/OTP de Elixir

El plugin de Elixir incluye Erlang/OTP como dependencias. Si necesitas una versión específica de OTP (por ejemplo, 24 vs 25), podés instalarla primero usando el plugin asdf de Erlang:

asdf plugin-add erlang https://github.com/asdf-vm/asdf-erlang.git
asdf install erlang 25.3.4
asdf global erlang 25.3.4

Luego asdf install elixir detectará la versión de OTP correcta.

5. Evita asdf install en contenedores CI

Para reducir el tamaño de las imágenes de Docker, considerá instalar solo la versión de Elixir (asdf install elixir 1.15.2) sin OTP. Luego, en tiempo de ejecución, instalá una versión mínima de OTP dentro del contenedor.

Errores comunes y cómo solucionarlos

Si ves un error de “descarga fallida”, verifica tu conexión a internet. Si la compilación falla con errores de gcc, instalá las herramientas de compilación (build-essential en Linux, llvm en macOS).

Ajustes avanzados y automatización

Usar asdf con Docker

Si estás construyendo una imagen de Docker para una aplicación Elixir, podés instalar asdf dentro del contenedor, pero tené en cuenta el tamaño. Un Dockerfile mínimo podría verse así:

FROM ubuntu:22.04

# Instalar dependencias
RUN apt-get update && apt-get install -y git curl make build-essential

# Instalar asdf
RUN git clone https://github.com/asdf-vm/asdf.git /root/.asdf && \
    echo 'source /root/.asdf/asdf.sh' >> /root/.bashrc

# Instalar plugin de Elixir y versión
RUN source /root/.bashrc && \
    asdf plugin-add elixir https://github.com/asdf-vm/asdf-elixir.git && \
    asdf install elixir 1.15.2 && \
    asdf global elixir 1.15.2

WORKDIR /app

Usar asdf en CI (GitHub Actions)

Puedes usar la acción oficial asdf-vm/setup-asdf@v2 que instala asdf y sus plugins automáticamente. Luego ejecutás asdf install elixir $ELIXIR_VERSION.

Usar asdf list-all elixir para buscar versiones

asdf list-all elixir

Salida esperada (ejemplo, solo las primeras líneas):

1.13.4
1.14.5
1.15.2
1.16.0

Esto es útil para definir la versión requerida en .tool-versions.

Conclusión

Configurar Elixir con asdf-vm es un proceso sencillo que te brinda un potente gestor de versiones capaz de manejar múltiples lenguajes. Siguiendo los pasos que describimos – instalación de asdf, adición del plugin de Elixir, instalación de una versión y configuración global/local – podés tener un entorno de desarrollo de Elixir limpio y reproducible en minutos.

Aplicar buenas prácticas (archivos .tool-versions, cacheo de descargas, pipelines CI) mantiene tu flujo de trabajo ordenado y escalable. Errores comunes como problemas de OTP o problemas de PATH se solucionan fácilmente con los pasos de solución de problemas mencionados.

Ahora podés centrarte en escribir código elegante en Elixir, en lugar de lidiar con instalaciones complicadas. Elige una versión que se adapte a tus necesidades, crea proyectos Mix, y observa cómo el soporte multi‑lenguaje de asdf hace que cambiar entre versiones de Node, Python, Ruby, etc., sea pan comido.

Próximos pasos:

• Explora el plugin asdf-erlang si necesitas versiones específicas de OTP.
• Configurá GitHub Actions en tu proyecto para instalar automáticamente la versión exacta de Elixir definida en .tool-versions.
• Considerá integrar asdf con tu IDE (por ejemplo, using el plugin de VS Code asdf-vscode) para navegación de versiones integrada.

¡Disfrutá del desarrollo con un entorno controlado y reproducible! 🚀