Se você trabalha com múltiplos projetos, provavelmente já encontrou algo parecido:
project-a
├── PHP 8.5
├── Node.js 24
└── Python 3.14
legacy-project
├── PHP 7.4
├── Node.js 20
└── Python 3.11
Enter fullscreen mode Exit fullscreen mode
O problema não é instalar essas linguagens.
O problema é conseguir manter várias versões instaladas ao mesmo tempo, trocar entre elas facilmente e garantir que todos os desenvolvedores do projeto utilizem o mesmo ambiente.
Tradicionalmente poderíamos usar:
- NVM para Node.js;
- Pyenv para Python;
- RVM ou rbenv para Ruby;
- ferramentas específicas para PHP.
Mas existe outra abordagem: utilizar um único gerenciador para todas elas.
É justamente aí que entram ferramentas como ASDF e Mise.
Neste artigo vamos ver:
- por que utilizar um version manager;
- ASDF vs Mise;
- como instalar ambos no Linux e macOS;
- como instalar PHP 8.5;
- como instalar Node.js 24 LTS;
- como instalar Python 3.14;
- como definir versões globais e por projeto;
- como compartilhar o ambiente com sua equipe.
Atualizado em agosto de 2026.
Por que usar um version manager?
Imagine que sua máquina tenha PHP 8.5 instalado globalmente.
Então aparece um projeto legado que depende de:
PHP 7.4
Enter fullscreen mode Exit fullscreen mode
Outro projeto utiliza:
PHP 8.3
Enter fullscreen mode Exit fullscreen mode
E sua aplicação atual utiliza:
PHP 8.5
Enter fullscreen mode Exit fullscreen mode
Você poderia instalar diferentes pacotes do sistema e manipular o PATH manualmente.
Mas isso rapidamente fica difícil de manter.
Com um version manager podemos simplesmente definir:
legacy-api/
PHP 7.4
api/
PHP 8.3
new-api/
PHP 8.5
Enter fullscreen mode Exit fullscreen mode
E o runtime correto será utilizado de acordo com o projeto.
Isso traz algumas vantagens importantes:
- múltiplas versões instaladas simultaneamente;
- configuração específica por projeto;
- ambiente reproduzível;
- menos alterações no sistema operacional;
- facilidade para trabalhar com projetos legados;
- padronização entre desenvolvimento e CI/CD.
ASDF vs Mise
O ASDF popularizou bastante a ideia de utilizar uma única interface para gerenciar diversas linguagens.
O Mise surgiu posteriormente e mantém compatibilidade com boa parte desse ecossistema, mas atualmente vai além do gerenciamento de versões.
Uma comparação rápida:
Recurso ASDF Mise Gerenciar runtimes ✅ ✅ PHP ✅ ✅ Node.js ✅ ✅ Python ✅ ✅.tool-versions
✅
✅
mise.toml
❌
✅
Variáveis de ambiente
Limitado
✅
Task runner
❌
✅
Configuração completa de ambiente
Parcial
✅
O ASDF continua sendo uma excelente opção, principalmente em projetos que já utilizam .tool-versions.
Para novos ambientes, entretanto, o Mise costuma ser uma escolha mais interessante porque consegue centralizar:
runtimes
+
variáveis de ambiente
+
tarefas
+
configuração do projeto
Enter fullscreen mode Exit fullscreen mode
Tudo utilizando a mesma ferramenta.
Versões utilizadas
Neste tutorial utilizaremos:
PHP 8.5
Node.js 24 LTS
Python 3.14
Enter fullscreen mode Exit fullscreen mode
Apesar de existir uma versão mais recente do Node.js na linha Current, para desenvolvimento de aplicações normalmente faz mais sentido utilizar a versão LTS.
Também utilizaremos versões Major/Minor nos exemplos:
[email protected]
node@24
[email protected]
Enter fullscreen mode Exit fullscreen mode
O próprio gerenciador pode resolver a versão patch correspondente.
Em ambientes onde máxima reprodutibilidade é necessária, como CI/CD, podemos posteriormente fixar versões exatas.
Pré-requisitos
Antes de instalar PHP, Python e Node.js precisamos instalar algumas dependências.
Isso é especialmente importante para PHP e Python, que podem ser compilados durante a instalação.
Ubuntu / Debian
Atualize os pacotes:
sudo apt update
sudo apt upgrade -y
Enter fullscreen mode Exit fullscreen mode
Instale as ferramentas básicas:
sudo apt install -y
git
curl
build-essential
autoconf
bison
re2c
pkg-config
Enter fullscreen mode Exit fullscreen mode
Fedora
Atualize o sistema:
sudo dnf upgrade --refresh -y
Enter fullscreen mode Exit fullscreen mode
Instale:
sudo dnf install -y
git
curl
gcc
gcc-c++
make
autoconf
automake
bison
re2c
pkgconf-pkg-config
Enter fullscreen mode Exit fullscreen mode
macOS
No macOS utilizaremos Homebrew.
Caso ainda não tenha instalado:
https://brew.sh
Enter fullscreen mode Exit fullscreen mode
Depois:
brew update
Enter fullscreen mode Exit fullscreen mode
Instale:
brew install
git
curl
coreutils
autoconf
automake
bison
re2c
pkg-config
Enter fullscreen mode Exit fullscreen mode
Opção 1: Mise
Para uma nova configuração, começaremos pelo Mise.
Instalando no Linux ou macOS
Se estiver utilizando ZSH:
curl https://mise.run/zsh | sh
Enter fullscreen mode Exit fullscreen mode
Se estiver utilizando Bash:
curl https://mise.run/bash | sh
Enter fullscreen mode Exit fullscreen mode
Recarregue o shell.
ZSH:
source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode
Bash:
source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode
Verifique:
mise --version
Enter fullscreen mode Exit fullscreen mode
Mise no macOS com Homebrew
No macOS também podemos utilizar:
brew install mise
Enter fullscreen mode Exit fullscreen mode
Adicione ao ZSH:
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
Enter fullscreen mode Exit fullscreen mode
Recarregue:
source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode
E teste:
mise doctor
Enter fullscreen mode Exit fullscreen mode
Instalando Node.js com Mise
Node.js é provavelmente o runtime mais simples desse setup.
No Ubuntu/Debian, caso seja necessário compilar alguma versão:
sudo apt install -y python3 make g++
Enter fullscreen mode Exit fullscreen mode
No Fedora:
sudo dnf install -y python3 make gcc-c++
Enter fullscreen mode Exit fullscreen mode
Agora podemos instalar Node.js 24:
mise use --global node@24
Enter fullscreen mode Exit fullscreen mode
Verifique:
node --version
npm --version
Enter fullscreen mode Exit fullscreen mode
Para listar as versões instaladas:
mise list node
Enter fullscreen mode Exit fullscreen mode
Instalando Python com Mise
Python possui algumas dependências opcionais importantes.
Sem elas, módulos como ssl, sqlite3, bz2, lzma e readline podem não estar disponíveis corretamente.
Ubuntu / Debian
sudo apt install -y
build-essential
libssl-dev
zlib1g-dev
libbz2-dev
libreadline-dev
libsqlite3-dev
libffi-dev
liblzma-dev
tk-dev
uuid-dev
Enter fullscreen mode Exit fullscreen mode
Fedora
sudo dnf install -y
gcc
make
openssl-devel
zlib-devel
bzip2-devel
readline-devel
sqlite-devel
libffi-devel
xz-devel
tk-devel
Enter fullscreen mode Exit fullscreen mode
macOS
brew install
openssl@3
readline
sqlite3
xz
zlib
tcl-tk
Enter fullscreen mode Exit fullscreen mode
Agora:
mise use --global [email protected]
Enter fullscreen mode Exit fullscreen mode
Verifique:
python --version
Enter fullscreen mode Exit fullscreen mode
E:
python -m pip --version
Enter fullscreen mode Exit fullscreen mode
Instalando PHP com Mise
PHP normalmente é a linguagem que exige mais dependências.
Ubuntu / Debian
sudo apt install -y
build-essential
autoconf
bison
re2c
pkg-config
libcurl4-openssl-dev
libssl-dev
libxml2-dev
libsqlite3-dev
libonig-dev
libzip-dev
libreadline-dev
libicu-dev
libjpeg-dev
libpng-dev
libwebp-dev
libfreetype6-dev
libgmp-dev
libsodium-dev
libxslt1-dev
zlib1g-dev
Enter fullscreen mode Exit fullscreen mode
Se utilizar PostgreSQL:
sudo apt install -y libpq-dev
Enter fullscreen mode Exit fullscreen mode
Fedora
sudo dnf install -y
autoconf
bison
gcc
gcc-c++
make
re2c
pkgconf-pkg-config
openssl-devel
libcurl-devel
libxml2-devel
sqlite-devel
oniguruma-devel
libzip-devel
readline-devel
libicu-devel
libjpeg-turbo-devel
libpng-devel
libwebp-devel
freetype-devel
gmp-devel
libsodium-devel
libxslt-devel
zlib-devel
Enter fullscreen mode Exit fullscreen mode
PostgreSQL:
sudo dnf install -y libpq-devel
Enter fullscreen mode Exit fullscreen mode
macOS
brew install
autoconf
automake
bison
re2c
pkg-config
openssl@3
curl
libiconv
libzip
oniguruma
icu4c
libxml2
sqlite
readline
libpng
jpeg-turbo
webp
freetype
gmp
libsodium
Enter fullscreen mode Exit fullscreen mode
Para PostgreSQL:
brew install libpq
Enter fullscreen mode Exit fullscreen mode
Agora instale PHP:
mise use --global [email protected]
Enter fullscreen mode Exit fullscreen mode
Verifique:
php -v
Enter fullscreen mode Exit fullscreen mode
Confira as extensões disponíveis:
php -m
Enter fullscreen mode Exit fullscreen mode
Configuração global com Mise
Podemos definir nossas versões padrão:
mise use --global [email protected]
mise use --global node@24
mise use --global [email protected]
Enter fullscreen mode Exit fullscreen mode
Agora:
php -v
node -v
python --version
Enter fullscreen mode Exit fullscreen mode
utilizarão essas versões sempre que nenhum projeto possuir uma configuração específica.
Configuração por projeto
Essa é provavelmente a funcionalidade mais importante.
Crie um projeto:
mkdir my-project
cd my-project
Enter fullscreen mode Exit fullscreen mode
Configure os runtimes:
mise use [email protected]
mise use node@24
mise use [email protected]
Enter fullscreen mode Exit fullscreen mode
O Mise criará um arquivo:
mise.toml
Enter fullscreen mode Exit fullscreen mode
Semelhante a:
[tools]
php = "8.5"
node = "24"
python = "3.14"
Enter fullscreen mode Exit fullscreen mode
Adicione ao Git:
git add mise.toml
git commit -m "Configure development runtimes"
Enter fullscreen mode Exit fullscreen mode
Quando outro desenvolvedor clonar o projeto:
mise install
Enter fullscreen mode Exit fullscreen mode
E pronto.
O ambiente poderá ser reproduzido sem precisar documentar manualmente cada runtime necessário.
Executando outra versão temporariamente
Também podemos utilizar uma versão diferente sem alterar o projeto.
Python:
mise x [email protected] -- python --version
Enter fullscreen mode Exit fullscreen mode
Node.js:
mise x node@22 -- node --version
Enter fullscreen mode Exit fullscreen mode
PHP:
mise x [email protected] -- php -v
Enter fullscreen mode Exit fullscreen mode
Isso é extremamente útil em testes de compatibilidade.
Por exemplo:
mise x [email protected] -- php artisan test
Enter fullscreen mode Exit fullscreen mode
e depois:
mise x [email protected] -- php artisan test
Enter fullscreen mode Exit fullscreen mode
Você consegue testar a mesma aplicação em múltiplas versões sem alterar permanentemente o ambiente.
Instalando várias versões
Podemos manter diversas versões simultaneamente.
PHP:
mise install [email protected]
mise install [email protected]
mise install [email protected]
Enter fullscreen mode Exit fullscreen mode
Node.js:
mise install node@22
mise install node@24
Enter fullscreen mode Exit fullscreen mode
Python:
mise install [email protected]
mise install [email protected]
mise install [email protected]
Enter fullscreen mode Exit fullscreen mode
Liste tudo:
mise list
Enter fullscreen mode Exit fullscreen mode
Indo além dos runtimes com Mise
Uma das principais diferenças do Mise é que ele pode gerenciar mais do que versões.
Nosso mise.toml poderia ser:
[tools]
php = "8.5"
node = "24"
python = "3.14"
[env]
APP_ENV = "development"
[tasks.test]
run = "php artisan test"
[tasks.dev]
run = "npm run dev"
Enter fullscreen mode Exit fullscreen mode
Agora podemos executar:
mise run test
Enter fullscreen mode Exit fullscreen mode
ou:
mise run dev
Enter fullscreen mode Exit fullscreen mode
Isso começa a transformar o mise.toml em uma descrição do próprio ambiente de desenvolvimento.
Opção 2: ASDF
Se você já possui projetos utilizando ASDF, não existe necessidade de migrar imediatamente.
Ele continua sendo uma ótima solução.
Uma diferença importante em relação a tutoriais antigos é que o ASDF atual não utiliza mais exatamente o mesmo processo de instalação e comandos encontrados em artigos de alguns anos atrás.
Por exemplo, atualmente utilizamos:
asdf set
Enter fullscreen mode Exit fullscreen mode
em vez do fluxo antigo baseado principalmente em:
asdf global
asdf local
Enter fullscreen mode Exit fullscreen mode
Instalando ASDF no macOS
Com Homebrew:
brew install asdf
Enter fullscreen mode Exit fullscreen mode
Verifique:
asdf version
Enter fullscreen mode Exit fullscreen mode
Instalando ASDF no Linux
Instale primeiro:
Ubuntu/Debian:
sudo apt install -y git bash
Enter fullscreen mode Exit fullscreen mode
Fedora:
sudo dnf install -y git bash
Enter fullscreen mode Exit fullscreen mode
Uma opção é instalar o binário atual do ASDF conforme a documentação oficial.
Caso já tenha Go configurado, também podemos instalar através dele:
go install github.com/asdf-vm/asdf/cmd/asdf@latest
Enter fullscreen mode Exit fullscreen mode
Depois confirme:
asdf version
Enter fullscreen mode Exit fullscreen mode
Configurando os shims
Adicione ao seu shell:
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"
Enter fullscreen mode Exit fullscreen mode
Para ZSH, coloque em:
~/.zshrc
Enter fullscreen mode Exit fullscreen mode
Para Bash:
~/.bashrc
Enter fullscreen mode Exit fullscreen mode
Depois recarregue o terminal.
Adicionando plugins
O ASDF utiliza plugins para cada runtime.
Node.js:
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git
Enter fullscreen mode Exit fullscreen mode
Python:
asdf plugin add python https://github.com/asdf-community/asdf-python.git
Enter fullscreen mode Exit fullscreen mode
PHP:
asdf plugin add php https://github.com/asdf-community/asdf-php.git
Enter fullscreen mode Exit fullscreen mode
Liste:
asdf plugin list
Enter fullscreen mode Exit fullscreen mode
Instalando os runtimes com ASDF
As dependências do sistema são as mesmas que instalamos anteriormente.
Node.js
Descubra a versão disponível da linha 24:
asdf latest nodejs 24
Enter fullscreen mode Exit fullscreen mode
Instale a versão retornada:
asdf install nodejs <versao>
Enter fullscreen mode Exit fullscreen mode
Por exemplo:
asdf install nodejs 24.x.x
Enter fullscreen mode Exit fullscreen mode
Defina como padrão:
asdf set -u nodejs 24.x.x
Enter fullscreen mode Exit fullscreen mode
Python
Consulte:
asdf latest python 3.14
Enter fullscreen mode Exit fullscreen mode
Instale:
asdf install python <versao>
Enter fullscreen mode Exit fullscreen mode
Configure:
asdf set -u python <versao>
Enter fullscreen mode Exit fullscreen mode
PHP
Consulte:
asdf latest php 8.5
Enter fullscreen mode Exit fullscreen mode
Instale:
asdf install php <versao>
Enter fullscreen mode Exit fullscreen mode
Configure:
asdf set -u php <versao>
Enter fullscreen mode Exit fullscreen mode
.tool-versions
O ASDF utiliza tradicionalmente:
.tool-versions
Enter fullscreen mode Exit fullscreen mode
Exemplo:
php 8.5.x
nodejs 24.x.x
python 3.14.x
Enter fullscreen mode Exit fullscreen mode
Para criar essa configuração através da CLI:
asdf set php <versao>
asdf set nodejs <versao>
asdf set python <versao>
Enter fullscreen mode Exit fullscreen mode
Depois:
git add .tool-versions
git commit -m "Configure runtime versions"
Enter fullscreen mode Exit fullscreen mode
Outro desenvolvedor poderá executar:
asdf install
Enter fullscreen mode Exit fullscreen mode
para instalar todas as versões.
Mise também pode ler .tool-versions
Esse detalhe torna a migração bastante simples.
Imagine um projeto existente:
.tool-versions
Enter fullscreen mode Exit fullscreen mode
com:
php 8.5.x
nodejs 24.x.x
python 3.14.x
Enter fullscreen mode Exit fullscreen mode
Mesmo utilizando Mise, é possível aproveitar esse arquivo.
Isso permite testar a ferramenta sem necessariamente migrar imediatamente todo o projeto para mise.toml.
Versões exatas ou Major/Minor?
Durante o desenvolvimento pessoal, isto pode ser suficiente:
[tools]
php = "8.5"
node = "24"
python = "3.14"
Enter fullscreen mode Exit fullscreen mode
Mas existe uma consequência.
Hoje:
[email protected]
Enter fullscreen mode Exit fullscreen mode
pode resolver para uma determinada versão patch.
Daqui alguns meses poderá resolver para uma versão mais nova.
Para projetos em equipe ou CI/CD, portanto, pode ser melhor utilizar:
[tools]
php = "8.5.x"
node = "24.x.x"
python = "3.14.x"
Enter fullscreen mode Exit fullscreen mode
substituindo os valores pelas versões exatas escolhidas no momento da configuração.
O objetivo é garantir:
developer A
=
developer B
=
CI
=
build
Enter fullscreen mode Exit fullscreen mode
Como verificar qual versão está sendo utilizada?
Alguns problemas aparentemente relacionados ao runtime são simplesmente problemas de PATH.
Confira:
which php
which node
which python
Enter fullscreen mode Exit fullscreen mode
Com Mise:
mise which php
mise which node
mise which python
Enter fullscreen mode Exit fullscreen mode
Com ASDF:
asdf which php
asdf which node
asdf which python
Enter fullscreen mode Exit fullscreen mode
Também confira diretamente:
php -v
node -v
python --version
Enter fullscreen mode Exit fullscreen mode
Meu setup atualmente
Para uma máquina nova, meu setup seria baseado em Mise:
mise use --global [email protected]
mise use --global node@24
mise use --global [email protected]
Enter fullscreen mode Exit fullscreen mode
E dentro de cada projeto:
mise use [email protected]
mise use node@24
mise use [email protected]
Enter fullscreen mode Exit fullscreen mode
Gerando:
[tools]
php = "8.5"
node = "24"
python = "3.14"
Enter fullscreen mode Exit fullscreen mode
Para projetos onde quero máxima previsibilidade, depois fixaria as versões patch exatas.
Então, ASDF ou Mise?
Minha regra atualmente seria simples.
Projeto existente com ASDF
Continue com ASDF.
Não existe motivo para criar uma migração apenas porque existe uma ferramenta mais nova.
Máquina ou projeto novo
Eu utilizaria Mise.
Ele resolve o mesmo problema de gerenciamento de runtimes e ainda permite evoluir o setup posteriormente adicionando:
environment variables
tasks
development tools
project configuration
Enter fullscreen mode Exit fullscreen mode
sem precisar introduzir novas ferramentas.
Conclusão
Não importa se você trabalha com:
PHP
Node.js
Python
Ruby
Go
Java
Enter fullscreen mode Exit fullscreen mode
em algum momento diferentes projetos provavelmente exigirão versões diferentes dessas ferramentas.
Um gerenciador como ASDF ou Mise evita que você precise instalar um version manager diferente para cada linguagem.
Mais importante ainda: ele transforma a versão utilizada pelo projeto em configuração versionável.
Em vez de escrever na documentação:
Instale PHP 8.5, Node.js 24 e Python 3.14.
o próprio projeto pode declarar:
[tools]
php = "8.5"
node = "24"
python = "3.14"
Enter fullscreen mode Exit fullscreen mode
E então:
mise install
Enter fullscreen mode Exit fullscreen mode
Isso reduz diferenças entre ambientes, facilita onboarding e evita uma boa quantidade de problemas do tipo:
Na minha máquina funciona.
Para projetos novos, atualmente considero o Mise uma das opções mais interessantes para gerenciar um ambiente de desenvolvimento moderno.
O ASDF, entretanto, continua extremamente relevante — especialmente pela simplicidade, maturidade e enorme quantidade de projetos que já utilizam .tool-versions.
답글 남기기