asdf-vm: versões de ferramentas sem complicação

Quem trabalha com desenvolvimento acaba encontrando projetos que dependem de versões diferentes da mesma ferramenta. Um projeto pode usar uma versão específica do Python, enquanto outro precisa de uma versão diferente. O mesmo acontece com Node.js, Ruby, Java e outras linguagens.

O asdf-vm resolve esse problema com uma ideia simples: instalar diferentes versões de ferramentas e escolher qual delas deve estar ativa em cada projeto. Em vez de alterar manualmente o sistema toda vez que mudo de contexto, deixo a versão registrada junto ao projeto.

O que é o asdf-vm

O asdf-vm é um gerenciador de versões extensível por plugins. Cada plugin adiciona suporte a uma ferramenta, e o arquivo .tool-versions registra as versões usadas naquele diretório.

Essa combinação é útil porque mantém o ambiente reproduzível. Quando entro em um projeto, o asdf identifica a configuração local e ajusta os comandos para usarem as versões esperadas.

Não preciso manter uma instalação global confusa ou lembrar qual versão foi escolhida para cada aplicação. A própria pasta do projeto passa a documentar parte importante do ambiente.

Instalando um plugin

Depois de instalar o asdf-vm e carregá-lo no shell, adiciono o plugin da ferramenta que quero administrar. Para Python, por exemplo:

asdf plugin add python

Posso conferir os plugins disponíveis e as versões que já estão instaladas:

asdf plugin list
asdf list python

O plugin é responsável por integrar o asdf ao processo de instalação daquela ferramenta. Por isso, vale consultar a documentação do plugin quando houver dependências específicas no sistema.

Instalando versões diferentes

Com o plugin configurado, posso instalar mais de uma versão:

asdf install python 3.11.7
asdf install python 3.12.1

Depois escolho uma versão padrão para o usuário ou uma versão específica para um projeto. A configuração local fica registrada no .tool-versions:

asdf local python 3.11.7

Em versões mais recentes do asdf, o comando equivalente pode ser asdf set python 3.11.7. O resultado é o mesmo: o diretório passa a declarar qual versão deve ser utilizada.

O arquivo gerado é simples:

python 3.11.7

Esse arquivo pode ser versionado junto com o código. Assim, outra pessoa consegue saber qual versão foi usada para desenvolver e testar o projeto.

A troca acontece automaticamente

Depois de entrar em um diretório com .tool-versions, o asdf ajusta os caminhos dos executáveis. Com isso, comandos comuns continuam funcionando:

python --version
which python

Quando saio do projeto, volto a usar a configuração do diretório pai. Essa troca automática é muito mais confortável do que editar variáveis de ambiente ou substituir links simbólicos manualmente.

Também posso manter versões diferentes de ferramentas no mesmo computador sem misturar os arquivos de uma instalação com os de outra. Isso facilita testar uma atualização sem interromper um projeto que ainda depende da versão anterior.

Mais do que Python

O asdf-vm não é limitado ao Python. Dependendo dos plugins instalados, ele pode administrar ferramentas como:

• Node.js para aplicações web.
• Ruby para projetos que usam Rails.
• Java para aplicações e ferramentas corporativas.
• Terraform para infraestrutura.
• Golang para aplicações compiladas.
• Elixir, Erlang e outras linguagens.

A interface continua parecida entre elas: plugin, instalação da versão e registro no .tool-versions.

Essa uniformidade é uma das maiores vantagens. Não preciso aprender um gerenciador completamente diferente para cada linguagem que aparece no meu trabalho.

O que o asdf não substitui

O asdf-vm administra versões de ferramentas, mas não substitui o gerenciador de pacotes da distribuição. Dependências do sistema, bibliotecas nativas e compiladores ainda podem precisar ser instalados pelos repositórios do Linux.

Da mesma forma, o asdf não cria ambientes Python isolados por projeto. Para isso, continuo usando venv, uv ou outra ferramenta adequada. O asdf escolhe o interpretador; o ambiente virtual organiza as dependências da aplicação.

Separar essas responsabilidades deixa a configuração mais clara e evita esperar que uma única ferramenta resolva todos os problemas do ambiente.

Minha conclusão

O asdf-vm entrou no meu ferramental porque simplifica uma situação comum: trabalhar com projetos que não usam exatamente as mesmas versões. A instalação fica centralizada, a troca acontece conforme o diretório e o .tool-versions registra uma parte importante da configuração.

Em vez de lutar contra versões globais ou reinstalar ferramentas a cada projeto, posso manter um ambiente organizado e previsível. Para quem desenvolve em mais de uma linguagem, o asdf-vm é uma solução simples que economiza tempo no dia a dia.