dotnetup: como instalar e gerenciar o SDK do .NET

O que é o dotnetup

O dotnetup é uma ferramenta de linha de comando multiplataforma que gerencia instalações do .NET no nível do usuário. Na prática, ele cumpre no ecossistema .NET o mesmo papel que o rustup cumpre no Rust e o nvm cumpre no Node.

A ideia central é simples: você declara o que quer manter instalado e a ferramenta cuida do resto. Por isso, o foco deixa de ser a versão exata e passa a ser a intenção, como "quero sempre o .NET 10 mais recente".

Segundo a documentação oficial no Microsoft Learn, o dotnetup instala versões estáveis, preview, daily ou exatas. Ele também mantém vários SDKs lado a lado, lê o global.json do repositório e atualiza canais sem mexer em versões fixadas.

Outro ponto importante é que ele nunca escreve em diretórios do sistema. Ou seja, pastas como /usr/share/dotnet ou Program Files\dotnet continuam intactas.

Por que a Microsoft criou um gerenciador de toolchain

Quem trabalha com .NET no macOS ou no Linux conhece bem a quantidade de caminhos para instalar o SDK. Existem o apt, o brew, os tarballs de cada plataforma e os scripts dotnet-install.sh.

Todos esses métodos funcionam, mas cada um traz seus atritos. Muitas vezes eles exigem sudo, espalham arquivos por diretórios do sistema e dificultam a convivência de várias versões.

Além disso, cada método tem comandos e regras próprias. Assim, quem alterna entre máquinas e sistemas operacionais precisa decorar vários fluxos para fazer a mesma coisa.

O dotnetup nasceu para reduzir essa quantidade de conceitos. De acordo com o anúncio no blog do .NET, a ferramenta se apoia em cinco pilares:

• Experiência consistente, com os mesmos comandos em todas as plataformas.
• Execução sem administrador, porque tudo fica em pastas do próprio usuário.
• Gerenciamento lado a lado de versões de serviço, preview e builds diárias.
• Rastreamento de intenção, então você acompanha majors ou feature bands e recebe as atualizações mensais.
• Respeito ao global.json, para que os builds do time continuem previsíveis.

Existe também um motivo técnico. Em um comentário no post de lançamento, Chet Husk, gerente de produto do SDK, explicou que a equipe queria um bootstrapper pequeno e nativo.

Dessa forma, ninguém precisa baixar os cerca de 200 MB do SDK completo apenas para começar. Esse ponto de entrada menor também facilita o uso em cenários como GitHub Actions e Azure DevOps.

Como instalar o dotnetup no macOS e no Linux

A instalação começa com um script de bootstrap. Ele baixa o executável, valida o checksum SHA-512 e coloca o binário na pasta ~/.dotnetup.

No macOS com Zsh, rode o comando abaixo:

curl -fsSL https://aka.ms/dotnetup/get-dotnetup.sh | zsh

No Linux com Bash, o comando é praticamente o mesmo:

curl -fsSL https://aka.ms/dotnetup/get-dotnetup.sh | bash

Caso você use PowerShell, também existe um script equivalente:

irm https://aka.ms/dotnetup/get-dotnetup.ps1 | iex

Para rodar o script no macOS ou no Linux, você precisa do curl ou do wget. Além disso, o sistema precisa ter o sha512sum ou o shasum para verificar o arquivo baixado.

A ferramenta suporta x64 e Arm64 no Windows, no macOS e no Linux, inclusive em distribuições com musl, como o Alpine. Por fim, o script imprime as instruções para colocar o dotnetup no PATH, então abra um novo terminal depois de aplicá-las.

dotnetup init

dotnetup list

dotnetup install latest
dotnetup env set shell
dotnet --version

dotnetup dotnet -- --version

Canais e versões no dotnetup

Para usar bem o dotnetup, você precisa entender a diferença entre canal e versão exata. Um canal descreve um conjunto de versões, enquanto uma versão exata descreve apenas uma.

dotnetup runtime install runtime@10.0
dotnetup runtime install aspnetcore@10.0
dotnetup runtime install 10.0

Como o dotnetup organiza as instalações

O dotnetup separa o que você pede dos arquivos que ele instala. Esse modelo permite que vários requisitos compartilhem a mesma instalação e que a limpeza aconteça de forma segura.

Cada pedido vira uma especificação de instalação, que guarda o componente e o canal ou a versão. Além disso, ela registra a origem: um comando explícito ou um arquivo global.json.

A raiz padrão das instalações fica dentro da pasta de dados da ferramenta:

Se quiser outro diretório, use a opção --install-path. Por sua vez, a ordem de prioridade é a opção explícita, depois o caminho do global.json e, por fim, a raiz padrão.

Todo esse estado fica em um manifesto chamado dotnetup_manifest.json. A documentação recomenda não editar esse arquivo à mão, porque a ferramenta guarda um hash para detectar alterações externas.

Quando uma instalação não deve entrar no rastreamento, existe a opção --untracked. Nesse caso, o dotnetup não lista, não atualiza e não remove esses arquivos depois.

Mantendo SDKs e runtimes atualizados

Todo mês o time do .NET publica atualizações de serviço com correções de segurança e de qualidade. Em instalações do sistema, nem sempre você controla quando essas atualizações chegam.

Com o dotnetup, manter tudo em dia exige um único comando:

dotnetup update

Esse comando resolve de novo cada canal rastreado e instala a versão mais recente compatível. Por exemplo, o canal 10.0 acompanha o .NET 10, enquanto latest segue o SDK estável mais novo, inclusive em novas versões major.

Se preferir um escopo menor, existem variações do comando:

# Atualiza apenas os requisitos de SDK
dotnetup sdk update

# Atualiza apenas os requisitos de runtime
dotnetup runtime update

Depois de uma atualização bem sucedida, a ferramenta roda uma coleta de lixo. Com isso, ela remove componentes que nenhum requisito restante utiliza.

Uma versão continua instalada sempre que outro canal ou versão exata ainda depende dela. Além disso, se uma atualização falhar, o dotnetup segue com as demais e só informa o erro no final.

Para deixar de acompanhar um canal, use sdk uninstall ou runtime uninstall. Em seguida, a ferramenta limpa as instalações que perderam a utilidade.

Lembre também que atualizar a máquina não corrige aplicações que você já publicou. Em aplicações self-contained, você ainda precisa republicar e reimplantar com o runtime novo.

Integração do dotnetup com o global.json

Muitos times fixam a versão do SDK no arquivo global.json para garantir builds previsíveis. O dotnetup entende esse arquivo e instala exatamente o que o repositório pede.

Para isso, basta rodar o comando sem informar um canal, a partir da pasta do projeto:

dotnetup sdk install

Nesse caso, o dotnetup procura o global.json mais próximo, subindo pelos diretórios até a raiz. Se não encontrar nenhum, ele usa o canal latest.

Considere o arquivo abaixo:

{
  "sdk": {
    "version": "10.0.103",
    "rollForward": "latestPatch"
  }
}

Com essa configuração, a ferramenta passa a rastrear a feature band 10.0.1xx. Isso acontece porque ela traduz a política de rollForward em um canal:

Quando quiser gravar a nova versão de volta no repositório, use a opção --update-global-json. Nesse caso, a ferramenta altera apenas o sdk.version e preserva a formatação original.

dotnetup sdk update --update-global-json

Se você mudar o global.json manualmente, rode dotnetup sdk install no repositório antes de atualizar. Caso contrário, a primeira atualização ainda pode processar o requisito antigo.

Testando builds preview e daily

Antes, testar uma build noturna significava caçar tarballs no GitHub e ajustar variáveis de ambiente à mão. Agora, previews e builds diárias funcionam como cidadãos de primeira classe.

Para instalar o SDK preview ao lado da sua versão estável, rode:

dotnetup sdk install preview

Se o objetivo for validar a correção de um bug, você também pode baixar o runtime diário mais recente:

dotnetup runtime install daily
dotnetup sdk install daily

Esse fluxo ajuda muito quem acompanha as novidades do .NET 11, como os Blazor AI components. Assim, você testa recursos novos sem afetar o ambiente que usa nos projetos em produção.

Porém, existe um cuidado importante. As builds diárias não passaram pela validação de release e não têm assinatura de código, por isso use-as apenas em testes rápidos.

dotnetup versus scripts dotnet-install

Uma dúvida natural é se os scripts dotnet-install.sh e dotnet-install.ps1 já não resolviam isso. De fato, eles cobrem boa parte do cenário, mas deixam algumas lacunas.

Em resumo, o dotnetup acrescenta gerenciamento real das instalações. Além disso, ele valida assinaturas e checksums, instala vários componentes em paralelo e oferece a mesma CLI em todas as plataformas.

Os scripts continuam úteis quando outro processo é dono do diretório de destino. Ainda assim, para o desenvolvimento diário, o novo gerenciador tende a ser a opção mais confortável.

Uso do dotnetup em pipelines de CI

Como o dotnetup dispensa privilégios de root e roda sem interação, ele se encaixa bem em agentes de CI efêmeros e em containers. Nesses ambientes, você monta rapidamente o SDK exato ou a build noturna que precisa testar.

Um passo de pipeline pode ficar bem enxuto:

curl -fsSL https://aka.ms/dotnetup/get-dotnetup.sh | bash
~/.dotnetup/dotnetup sdk install
~/.dotnetup/dotnetup dotnet -- build --configuration Release

Nesse exemplo, o segundo comando lê o global.json do repositório. Em seguida, o terceiro executa o build com o SDK gerenciado, sem alterar o PATH do agente.

Para scripts e relatórios, a listagem também oferece saída estruturada:

dotnetup list --format json

No roadmap, a Microsoft pretende integrar a ferramenta ao GitHub Actions e ao Azure DevOps. A ideia é substituir partes dessas integrações que hoje dependem dos scripts de instalação.

Se você está montando suas primeiras esteiras, vale conferir os cursos do balta.io, que cobrem Docker, Azure e GitHub Actions em projetos .NET reais.

Limitações da versão preview

Por enquanto, o dotnetup está em prévia pública. Por isso, comandos, opções e comportamentos ainda podem mudar entre versões, e o ciclo de suporte final ainda não existe.

A própria documentação indica outros métodos para máquinas de produção. Nesses casos, os instaladores oficiais, o gerenciador de pacotes da distribuição ou o Visual Studio continuam sendo a escolha recomendada.

Também existem limitações pontuais. Por exemplo, a prévia trata a primeira entrada de sdk.paths do global.json apenas como caminho, sem interpretar o valor especial $host$.

Além disso, a ferramenta ainda não gerencia instalações do sistema. A Microsoft já anunciou que vai adicionar esse suporte no Windows, porque lá esse tipo de instalação é muito comum.

Por fim, a equipe quer evoluir as skills para agentes de IA. O objetivo é que assistentes automatizados usem o dotnetup de forma natural, algo que conversa com práticas como o spec driven development.

Para manter a ferramenta em dia durante a prévia, rode:

dotnetup self update

Conclusão

O dotnetup resolve uma dor antiga de quem desenvolve com .NET fora do Windows. Ele substitui um conjunto de métodos diferentes por uma CLI única, previsível e sem necessidade de sudo.

Na prática, os ganhos aparecem em três frentes. Você atualiza tudo com um comando, testa previews sem medo e respeita o global.json do time automaticamente.

Ainda assim, lembre que a ferramenta está em prévia. Portanto, comece pela sua máquina de desenvolvimento e por pipelines de teste antes de levá-la para ambientes críticos.

Se encontrar problemas ou tiver sugestões, a equipe recebe feedback nas discussões do repositório dotnet/sdk. Então experimente o dotnetup, compartilhe sua experiência e ajude a moldar o futuro da instalação do .NET.

FAQ

O dotnetup precisa de sudo ou acesso root?

Não. A ferramenta guarda SDKs, runtimes e metadados inteiramente na pasta do usuário.

O dotnetup funciona no Windows?

Sim. Ele suporta Windows x64 e Arm64, mas o modo padrão everywhere altera o PATH do sistema e exige elevação.

O dotnetup remove a instalação do .NET que já existe na máquina?

Não. Ele nunca altera instalações do sistema, mas pode migrar SDKs existentes para a raiz gerenciada durante a configuração.

Uma versão exata é atualizada pelo dotnetup update?

Não. Versões exatas ficam fixadas, e apenas canais como latest, lts ou 10.0 avançam.

Posso usar o dotnetup em produção?

A documentação recomenda os instaladores oficiais em produção enquanto a ferramenta estiver em prévia pública.