Guia Completo do Rustup

O rustup é o instalador e gerenciador oficial de toolchains do Rust. Ele permite instalar, atualizar e alternar entre diferentes versões do compilador, adicionar targets de compilação cruzada e gerenciar componentes como clippy e rustfmt. Neste guia completo, vamos explorar todos os recursos do rustup.

Instalar o Rustup

Linux e macOS

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Para guias detalhados por sistema operacional, consulte:

Ubuntu | Fedora | Arch Linux | Debian
macOS

Windows

Baixe e execute o rustup-init.exe de rustup.rs ou veja o guia de instalação no Windows.

Verificar a instalação

rustup --version
rustup show

Gerenciar Toolchains

O Rust oferece três canais de release:

Canal	Frequência	Estabilidade	Uso
stable	A cada 6 semanas	Garantia de compatibilidade	Produção
beta	A cada 6 semanas	Pré-release do próximo stable	Teste de compatibilidade
nightly	Diariamente	Features experimentais	Desenvolvimento avançado

Instalar Toolchains

# Instalar stable (padrão)
rustup toolchain install stable

# Instalar nightly
rustup toolchain install nightly

# Instalar beta
rustup toolchain install beta

# Instalar versão específica
rustup toolchain install 1.80.0

# Instalar nightly de uma data específica
rustup toolchain install nightly-2026-02-20

Listar e Remover

# Listar toolchains instaladas
rustup toolchain list

# Remover uma toolchain
rustup toolchain uninstall nightly

# Ver informações detalhadas
rustup show

Definir Toolchain Padrão

# Definir stable como padrão global
rustup default stable

# Definir nightly como padrão global
rustup default nightly

# Usar uma toolchain pontualmente (sem alterar padrão)
cargo +nightly build
cargo +beta test
rustc +nightly --version

Overrides por Projeto

Você pode definir uma toolchain específica para cada diretório de projeto:

Método 1: Override por diretório

cd meu-projeto
rustup override set nightly

# Verificar
rustup show active-toolchain

# Remover override
rustup override unset

Método 2: Arquivo rust-toolchain.toml (Recomendado)

Crie um rust-toolchain.toml na raiz do projeto:

[toolchain]
channel = "nightly-2026-02-20"
components = ["rustfmt", "clippy", "rust-analyzer"]
targets = ["wasm32-unknown-unknown"]
profile = "default"

Vantagem: Este arquivo é versionado com o código, garantindo que toda a equipe use a mesma toolchain.

Método 3: Arquivo rust-toolchain (legado)

nightly-2026-02-20

Prefira o formato TOML, que é mais expressivo.

Componentes

Componentes são partes opcionais da toolchain:

Listar Componentes

# Componentes instalados
rustup component list --installed

# Todos os componentes disponíveis
rustup component list

Componentes Mais Usados

# Formatador de código
rustup component add rustfmt

# Linter
rustup component add clippy

# Language Server Protocol
rustup component add rust-analyzer

# Código-fonte da stdlib (necessário para IDEs)
rustup component add rust-src

# Documentação offline
rustup component add rust-docs

# LLVM tools (necessário para cobertura de código)
rustup component add llvm-tools-preview

# Miri (interpretador para detecção de undefined behavior)
rustup component add miri --toolchain nightly

Para configurar seu editor com estes componentes, veja o guia de VS Code ou Neovim.

Targets (Compilação Cruzada)

Targets permitem compilar para diferentes plataformas sem sair do seu sistema:

Listar Targets

# Targets instalados
rustup target list --installed

# Todos os targets disponíveis
rustup target list

Adicionar Targets Comuns

# Linux musl (binários estáticos)
rustup target add x86_64-unknown-linux-musl

# WebAssembly
rustup target add wasm32-unknown-unknown
rustup target add wasm32-wasi

# Windows (a partir do Linux/macOS)
rustup target add x86_64-pc-windows-gnu

# macOS ARM (a partir do Intel)
rustup target add aarch64-apple-darwin

# ARM Linux (Raspberry Pi)
rustup target add armv7-unknown-linux-gnueabihf
rustup target add aarch64-unknown-linux-gnu

# Android
rustup target add aarch64-linux-android
rustup target add armv7-linux-androideabi

Compilar para um Target

cargo build --target x86_64-unknown-linux-musl
cargo build --target wasm32-unknown-unknown

Para um guia completo sobre compilação cruzada, veja Cross-Compilation em Rust.

Profiles

Profiles controlam quais componentes são instalados por padrão:

# Minimal: apenas rustc e cargo
rustup set profile minimal

# Default: rustc, cargo, rustfmt, clippy, rust-docs
rustup set profile default

# Complete: todos os componentes disponíveis
rustup set profile complete

O profile minimal é ideal para CI/CD (veja GitHub Actions), enquanto default é recomendado para desenvolvimento.

Atualizar o Rust

# Atualizar todas as toolchains e o próprio rustup
rustup update

# Atualizar apenas uma toolchain
rustup update stable
rustup update nightly

# Ver o changelog da versão instalada
rustup doc --release-notes

Atualizar o Próprio Rustup

rustup self update

Nota: Em algumas distribuições Linux que instalam rustup via gerenciador de pacotes, o self update pode estar desabilitado. Atualize pelo gerenciador do sistema.

Documentação Offline

O rustup instala documentação completa do Rust localmente:

# Abrir a documentação no navegador
rustup doc

# Abrir a referência da stdlib
rustup doc --std

# Abrir o Rust Book
rustup doc --book

# Abrir a referência de uma crate da stdlib
rustup doc std::collections::HashMap

Solução de Problemas

Erro: “no override and no default toolchain set”

rustup default stable

Erro: “component is not available for download”

Alguns componentes não estão disponíveis em todas as versões nightly. Use uma data específica:

# Verificar disponibilidade
rustup component add clippy --toolchain nightly
# Se falhar, tente uma data anterior
rustup toolchain install nightly-2026-02-19
rustup component add clippy --toolchain nightly-2026-02-19

Espaço em disco

As toolchains podem ocupar bastante espaço. Para limpar:

# Remover toolchains não utilizadas
rustup toolchain uninstall nightly-2026-01-15

# Ver espaço usado
du -sh ~/.rustup/toolchains/*

# Limpar downloads em cache
rustup self clean

Próximos Passos

Com o rustup dominado:

Aprenda os comandos do Guia Completo do Cargo
Siga o tutorial de Primeiros Passos com Rust
Consulte o Cheatsheet Rust para referência rápida
Explore Cross-Compilation para aproveitar os targets
Veja as Perguntas Frequentes para dúvidas comuns

Se você gerencia toolchains em outras linguagens, confira o golang.com.br para comparar com o gerenciamento de versões do Go.

Última atualização: 23 de fevereiro de 2026. Para remover o rustup e o Rust completamente, veja Como Desinstalar Rust.