Rustup é o instalador oficial e gerenciador de toolchains da linguagem Rust. Ele instala o compilador rustc e o Cargo e permite manter lado a lado os canais stable, beta e nightly, alternar versões por projeto, adicionar componentes como rust-analyzer, clippy e rustfmt e instalar targets de cross-compilation.

Como instalar o Rust com Rustup?

No Linux e macOS rode 'curl --proto =https --tlsv1.2 -sSf https://sh.rustup.rs | sh'. No Windows baixe e execute o rustup-init.exe disponível em rustup.rs. Para instalação não-interativa, ideal em CI, acrescente '-s -- -y'. Depois confirme com 'rustc --version'.

Como atualizar o Rust para a versão mais recente?

Execute 'rustup update'. Esse comando atualiza todos os toolchains instalados (stable, beta e nightly) e seus componentes para a versão mais recente. Para atualizar apenas o próprio Rustup, use 'rustup self update'.

Qual a diferença entre stable, beta e nightly?

Stable é a versão estável, lançada a cada 6 semanas e recomendada para produção. Beta é a candidata à próxima stable, útil para testar compatibilidade. Nightly é a versão diária com features experimentais, necessária para usar recursos instáveis e ferramentas como o validador Miri.

Como definir a versão do Rust por projeto?

Crie um arquivo rust-toolchain.toml na raiz do projeto informando canal, componentes e targets. O Rustup lê esse arquivo automaticamente ao entrar no diretório, garantindo que todo o time use exatamente a mesma versão do compilador.

Rustup: Download, Instalação e Comandos

Rustup é o instalador e gerenciador oficial de versões do Rust. Para fazer o download, use o site oficial rustup.rs: no Windows, baixe o rustup-init.exe; no Linux e macOS, execute o comando abaixo. Ele instala o compilador (rustc), o Cargo e permite alternar entre toolchains stable, beta, nightly ou versões específicas.

# Download e instalação no Linux e macOS
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Resposta rápida: download, instalação e comandos

Objetivo	Comando ou ação
Baixar no Windows	Executar o `rustup-init.exe` de rustup.rs
Instalar no Linux/macOS	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh`
Confirmar a instalação	`rustup --version && rustc --version && cargo --version`
Atualizar o Rust e as toolchains	`rustup update`
Usar stable como padrão	`rustup default stable`
Instalar nightly	`rustup toolchain install nightly`
Listar toolchains	`rustup toolchain list`
Adicionar um target	`rustup target add <target>`
Instalar Clippy	`rustup component add clippy`
Remover Rust e Rustup	`rustup self uninstall`

Se você pesquisou apenas “rustup download”, use somente o domínio oficial rustup.rs. No Windows, o download correto é o rustup-init.exe; no Linux e no macOS, o instalador oficial é o script servido por sh.rustup.rs. Depois da instalação, rustup gerencia versões do compilador, enquanto cargo cria, testa e compila projetos.

O Cargo gerencia projetos e dependências; o Rustup coloca o compilador na máquina e garante a versão certa para cada projeto. Ele também adiciona componentes como rust-analyzer, clippy e rustfmt, além de targets para cross-compilation. Se você quer apenas começar a programar, siga o passo a passo completo de instalação do Rust.

Neste guia você encontra instalação no Windows, Linux e macOS, atualização, canais stable/nightly, rust-toolchain.toml, componentes, targets e perfis minimal, default e complete.

Instalação

Instalando o Rustup

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

# Windows (PowerShell)
# Baixe e execute rustup-init.exe de https://rustup.rs

# Instalação não-interativa (ideal para CI)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y

# Verificar instalação
rustup --version
# rustup 1.x.x (...)

rustc --version
# rustc 1.xx.x (...)

Após a instalação, adicione o diretório ao PATH (normalmente feito automaticamente):

# Adicionar ao ~/.bashrc, ~/.zshrc ou equivalente
source "$HOME/.cargo/env"

# Ou manualmente
export PATH="$HOME/.cargo/bin:$PATH"

Desinstalando

# Remover completamente o Rust e o Rustup
rustup self uninstall

Uso Básico

Gerenciando Canais (Channels)

O Rust possui três canais de release:

stable: Versão estável, lançada a cada 6 semanas
beta: Próxima versão estável, para testes
nightly: Versão diária com features experimentais

# Instalar toolchains
rustup install stable
rustup install beta
rustup install nightly

# Instalar uma versão específica
rustup install 1.85.0
rustup install nightly-2026-08-01

# Definir o toolchain padrão
rustup default stable
rustup default nightly

# Ver toolchains instaladas
rustup toolchain list
# stable-x86_64-unknown-linux-gnu (default)
# beta-x86_64-unknown-linux-gnu
# nightly-x86_64-unknown-linux-gnu

# Executar um comando com toolchain específica
rustup run nightly cargo build
rustup run beta rustc --version

# Atalho com +
cargo +nightly build
cargo +beta test
rustc +nightly --version

Atualizando Toolchains

# Atualizar todas as toolchains instaladas
rustup update

# Atualizar apenas uma toolchain
rustup update stable
rustup update nightly

# Ver informações sobre a versão atual
rustup show
# Default host: x86_64-unknown-linux-gnu
# rustup home:  /home/usuario/.rustup
#
# installed toolchains
# --------------------
# stable-x86_64-unknown-linux-gnu (default)
# nightly-x86_64-unknown-linux-gnu
#
# active toolchain
# ----------------
# stable-x86_64-unknown-linux-gnu (default)
# rustc 1.77.0 (aedd173a2 2024-03-17)

# Verificar se há atualizações disponíveis
rustup check

Removendo Toolchains

# Remover uma toolchain
rustup toolchain uninstall nightly
rustup toolchain uninstall 1.70.0

# Listar e remover toolchains antigas
rustup toolchain list
rustup toolchain uninstall nightly-2024-01-01

Recursos Avançados

Componentes

Componentes são partes opcionais de uma toolchain:

# Listar componentes disponíveis
rustup component list

# Listar componentes instalados
rustup component list --installed
# cargo-x86_64-unknown-linux-gnu
# clippy-x86_64-unknown-linux-gnu
# rust-docs-x86_64-unknown-linux-gnu
# rust-std-x86_64-unknown-linux-gnu
# rustc-x86_64-unknown-linux-gnu
# rustfmt-x86_64-unknown-linux-gnu

# Instalar componentes essenciais
rustup component add rust-analyzer    # LSP server para IDEs
rustup component add rust-src         # Código fonte da stdlib
rustup component add clippy           # Linter (normalmente já incluso)
rustup component add rustfmt          # Formatador (normalmente já incluso)
rustup component add llvm-tools       # Ferramentas LLVM (profiling, coverage)
rustup component add miri             # Interpretador para detectar UB (nightly)

# Instalar componente para toolchain específica
rustup component add rust-src --toolchain nightly
rustup component add miri --toolchain nightly

# Remover componente
rustup component remove rust-docs

Componentes mais importantes:

Componente	Descrição	Uso
`clippy`	Linter oficial	Análise estática de código
`rustfmt`	Formatador	Formatação consistente
`rust-analyzer`	LSP server	Integração com editores
`rust-src`	Código fonte stdlib	Navegação em IDEs, Miri
`llvm-tools`	Ferramentas LLVM	Coverage, profiling
`miri`	Interpretador	Detecção de undefined behavior
`rust-docs`	Documentação offline	Referência local

Override por Projeto (rust-toolchain.toml)

O arquivo rust-toolchain.toml na raiz do projeto define qual toolchain usar:

# rust-toolchain.toml
[toolchain]
channel = "1.75.0"
components = ["rust-src", "rust-analyzer", "clippy", "rustfmt"]
targets = ["x86_64-unknown-linux-gnu", "wasm32-unknown-unknown"]
profile = "default"

Exemplos de configuração:

# Projeto que requer nightly (fixe uma data para reprodutibilidade)
[toolchain]
channel = "nightly-2026-08-01"
components = ["rust-src", "clippy", "rustfmt"]

# Projeto com versão mínima fixa
[toolchain]
channel = "1.85.0"
components = ["clippy", "rustfmt"]

# Projeto WASM
[toolchain]
channel = "stable"
targets = ["wasm32-unknown-unknown"]
components = ["rust-src"]

Override via linha de comando:

# Override por diretório
rustup override set nightly
rustup override set 1.75.0

# Ver overrides ativos
rustup override list
# /home/usuario/projeto-x    nightly-x86_64-unknown-linux-gnu

# Remover override
rustup override unset
rustup override unset --path /home/usuario/projeto-x

Cross-Compilation

Cross-compilation permite compilar para plataformas diferentes da máquina host:

# Listar todos os targets disponíveis
rustup target list

# Listar targets instalados
rustup target list --installed

# Adicionar targets comuns
rustup target add x86_64-unknown-linux-musl      # Linux com musl (binários estáticos)
rustup target add aarch64-unknown-linux-gnu       # Linux ARM64
rustup target add x86_64-pc-windows-gnu           # Windows (GNU)
rustup target add x86_64-pc-windows-msvc          # Windows (MSVC)
rustup target add x86_64-apple-darwin             # macOS Intel
rustup target add aarch64-apple-darwin            # macOS Apple Silicon
rustup target add wasm32-unknown-unknown          # WebAssembly
rustup target add wasm32-wasip1                   # WebAssembly com WASI Preview 1
rustup target add aarch64-linux-android           # Android ARM64
rustup target add armv7-unknown-linux-gnueabihf   # Raspberry Pi

# Adicionar target para toolchain específica
rustup target add wasm32-unknown-unknown --toolchain nightly

# Remover target
rustup target remove aarch64-linux-android

Compilando para outro target:

# Compilar para Linux com musl (binários estáticos)
cargo build --target x86_64-unknown-linux-musl --release

# Compilar para WebAssembly
cargo build --target wasm32-unknown-unknown --release

# Compilar para Windows a partir do Linux
cargo build --target x86_64-pc-windows-gnu --release

# Compilar para ARM64 (ex: Raspberry Pi 4, AWS Graviton)
cargo build --target aarch64-unknown-linux-gnu --release

Configuração de cross-compilation no .cargo/config.toml:

# .cargo/config.toml

# Configurar linker para targets específicos
[target.x86_64-unknown-linux-musl]
linker = "x86_64-linux-musl-gcc"

[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"

[target.x86_64-pc-windows-gnu]
linker = "x86_64-w64-mingw32-gcc"

# Compilar sempre para um target específico
[build]
target = "x86_64-unknown-linux-musl"

Usando cross para cross-compilation simplificada:

# Instalar cross (usa Docker para cross-compilation)
cargo install cross

# Compilar para ARM64 sem configurar toolchain manualmente
cross build --target aarch64-unknown-linux-gnu --release

# Testar em outra arquitetura via emulação
cross test --target aarch64-unknown-linux-gnu

Profiles

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

# Listar profiles disponíveis
# minimal: rustc, rust-std, cargo
# default: minimal + clippy, rustfmt, rust-docs
# complete: todos os componentes

# Definir profile
rustup set profile minimal   # CI/CD
rustup set profile default   # Desenvolvimento
rustup set profile complete  # Tudo disponível

Proxies e Ferramentas

O Rustup instala proxies que redirecionam para a toolchain ativa:

# Ferramentas disponíveis via proxy
rustc      # Compilador Rust
cargo      # Gerenciador de pacotes
rustdoc    # Gerador de documentação
rust-gdb   # Debugger GDB para Rust
rust-lldb  # Debugger LLDB para Rust
rustfmt    # Formatador
cargo-fmt  # Formatador via Cargo
clippy-driver  # Driver do Clippy
cargo-clippy   # Clippy via Cargo

Solução de problemas do Rustup

`rustup: command not found` no Linux ou macOS

Esse erro normalmente significa que a instalação terminou, mas o terminal atual ainda não carregou o diretório ~/.cargo/bin no PATH. Primeiro execute:

source "$HOME/.cargo/env"
rustup --version

Se funcionar, abra um novo terminal. Caso o erro volte, confira se o seu shell carrega o arquivo correto:

# Bash
echo 'source "$HOME/.cargo/env"' >> ~/.bashrc

# Zsh
echo 'source "$HOME/.cargo/env"' >> ~/.zshrc

Não instale uma segunda cópia do Rust antes de verificar o PATH. Misturar o Rust da distribuição Linux com uma instalação do rustup pode fazer cargo, rustc e rustup apontarem para diretórios diferentes. Use which rustup, which rustc e which cargo para diagnosticar.

O Windows pede Visual Studio ou um linker

No Windows com a toolchain MSVC, Rust precisa das ferramentas nativas de compilação e link. Instale o Visual Studio Build Tools com a carga Desenvolvimento para desktop com C++ e o Windows SDK. Depois feche e reabra o PowerShell antes de repetir cargo build.

Se o erro mencionar link.exe, kernel32.lib ou ferramentas C++ ausentes, o problema geralmente não está no Cargo nem no código Rust: está nos pré-requisitos do toolchain MSVC. O guia de Rust no Windows cobre a instalação completa e a alternativa com WSL2.

`rustup update` falha ou fica preso

Comece verificando o estado atual:

rustup show
rustup check
rustup update stable

Em redes corporativas, proxy, inspeção TLS ou bloqueio de downloads pode interromper a atualização. Confirme acesso aos domínios oficiais do projeto e siga a política de proxy da organização. Evite desativar validação TLS ou executar instaladores copiados de fontes não oficiais.

Se apenas um componente falhar, remova e adicione novamente o componente na toolchain correta:

rustup component remove clippy --toolchain stable
rustup component add clippy --toolchain stable

O projeto usa a versão errada do Rust

Dentro do diretório do projeto, rode:

rustup show active-toolchain
rustup override list

Um arquivo rust-toolchain.toml ou um override de diretório tem prioridade sobre o padrão definido por rustup default stable. Se o override foi criado por engano, remova-o com:

rustup override unset

Para projetos compartilhados, prefira rust-toolchain.toml: ele é versionado no Git e comunica a mesma toolchain para todo o time e para a CI. Overrides locais são úteis para testes temporários, mas são invisíveis para outros desenvolvedores.

O target foi instalado, mas o link falha

rustup target add instala a biblioteca padrão para o target; ele não garante que o sistema tenha linker, SDK, bibliotecas C ou sysroot necessários. Por exemplo, adicionar aarch64-unknown-linux-gnu não instala automaticamente um linker ARM64.

Quando o erro acontece na etapa de link, verifique o guia de cross-compilation em Rust. Para builds Linux multi-arquitetura, ferramentas como cross e cargo-zigbuild podem simplificar a configuração. Para WebAssembly com WASI Preview 1, use o nome atual wasm32-wasip1, não o target antigo wasm32-wasi.

Rustup, Cargo e rustc mostram versões incompatíveis

Compare os caminhos e a toolchain ativa:

which rustup rustc cargo      # Linux/macOS
where.exe rustup rustc cargo  # Windows
rustup show active-toolchain
rustup which rustc

Os binários gerenciados pelo rustup normalmente ficam em ~/.cargo/bin no Linux/macOS e em %USERPROFILE%\.cargo\bin no Windows. Se outro diretório aparece antes no PATH, remova a instalação duplicada ou ajuste a ordem conscientemente. Depois confirme com rustc --version e cargo --version.

Boas Práticas

1. Use rust-toolchain.toml em Todo Projeto

# rust-toolchain.toml
# Garante que todos os desenvolvedores usam a mesma versão
[toolchain]
channel = "1.85.0"
components = ["clippy", "rustfmt", "rust-analyzer"]

2. Mantenha Toolchains Atualizadas

# Atualize regularmente
rustup update

# Crie um alias para atualizar tudo
# No ~/.bashrc ou ~/.zshrc:
alias rust-update='rustup update && cargo install-update -a'

3. Use minimal Profile para CI

# No CI, instale apenas o necessário
rustup set profile minimal
rustup install stable
rustup component add clippy rustfmt

4. Limpe Toolchains Não Utilizadas

# Verificar espaço usado
du -sh ~/.rustup/

# Listar e remover toolchains antigas
rustup toolchain list
rustup toolchain uninstall nightly-2024-01-01

# Remover targets não usados
rustup target list --installed
rustup target remove aarch64-linux-android

5. Configure rust-analyzer Corretamente

// .vscode/settings.json
{
    "rust-analyzer.check.command": "clippy",
    "rust-analyzer.cargo.features": "all",
    "rust-analyzer.procMacro.enable": true,
    "rust-analyzer.imports.granularity.group": "module"
}

Exemplos Práticos

Exemplo 1: Setup Completo para Desenvolvimento

#!/bin/bash
# setup-rust.sh - Script de setup para novos desenvolvedores

set -euo pipefail

echo "=== Instalando Rust via Rustup ==="
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

echo "=== Configurando toolchain ==="
rustup default stable
rustup component add rust-analyzer rust-src clippy rustfmt

echo "=== Instalando targets para cross-compilation ==="
rustup target add wasm32-unknown-unknown
rustup target add x86_64-unknown-linux-musl

echo "=== Instalando nightly (para cargo-expand e miri) ==="
rustup install nightly
rustup component add miri rust-src --toolchain nightly

echo "=== Instalando ferramentas essenciais ==="
cargo install cargo-watch
cargo install cargo-expand
cargo install cargo-audit
cargo install cargo-nextest
cargo install cargo-deny

echo "=== Verificação ==="
rustc --version
cargo --version
rustup show

echo "=== Setup concluído! ==="

Exemplo 2: Configuração de CI/CD

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test-stable:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy, rustfmt
      - uses: Swatinem/rust-cache@v2
      - run: cargo fmt --check
      - run: cargo clippy --all-targets -- -D warnings
      - run: cargo test --all-features

  test-nightly:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@nightly
      - uses: Swatinem/rust-cache@v2
      - run: cargo test --all-features

  test-msrv:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: "1.70.0"  # MSRV do projeto
      - uses: Swatinem/rust-cache@v2
      - run: cargo test --all-features

  cross-compile:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        target:
          - x86_64-unknown-linux-musl
          - aarch64-unknown-linux-gnu
          - wasm32-unknown-unknown
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.target }}
      - run: cargo build --target ${{ matrix.target }} --release

Exemplo 3: Projeto com Nightly Features

# rust-toolchain.toml para projeto que precisa de nightly
[toolchain]
channel = "nightly-2026-08-01"
components = ["rust-src", "clippy", "rustfmt", "miri"]

// src/main.rs
// Ativar features experimentais do nightly
#![feature(let_chains)]
#![feature(async_closure)]

use std::collections::HashMap;

fn processar_dados(dados: &HashMap<String, Option<Vec<i32>>>) {
    for (chave, valor) in dados {
        // let chains - feature do nightly
        if let Some(numeros) = valor
            && !numeros.is_empty()
        {
            let soma: i32 = numeros.iter().sum();
            println!("{chave}: soma = {soma}, quantidade = {}", numeros.len());
        }
    }
}

fn main() {
    let mut dados = HashMap::new();
    dados.insert("vendas".to_string(), Some(vec![100, 200, 300]));
    dados.insert("custos".to_string(), Some(vec![50, 75]));
    dados.insert("vazio".to_string(), None);

    processar_dados(&dados);
}

Exemplo 4: Usando Miri para Detectar Undefined Behavior

# Instalar Miri no nightly
rustup component add miri --toolchain nightly

# Executar testes com Miri
cargo +nightly miri test

# Executar binário com Miri
cargo +nightly miri run

# Miri com configurações específicas
MIRIFLAGS="-Zmiri-disable-isolation" cargo +nightly miri test

// src/lib.rs - Miri detecta este tipo de bug

#[cfg(test)]
mod tests {
    #[test]
    fn teste_seguro() {
        // Miri verifica que este código é seguro
        let mut vec = vec![1, 2, 3];
        let primeiro = &vec[0];
        println!("Primeiro: {}", primeiro);
        // Não modifica vec enquanto primeiro está emprestado
        drop(primeiro);
        vec.push(4);
        assert_eq!(vec.len(), 4);
    }

    #[test]
    fn teste_com_raw_pointers() {
        // Miri verifica operações com ponteiros raw
        let mut x = 42;
        let ptr = &mut x as *mut i32;
        unsafe {
            *ptr = 100;
            assert_eq!(*ptr, 100);
        }
    }
}

Comparação com Alternativas

Característica	Rustup	nvm (Node.js)	pyenv (Python)	sdkman (Java)
Instalação	Oficial	Comunidade	Comunidade	Comunidade
Cross-compilation	Integrado	N/A	N/A	N/A
Componentes	Gerenciados	N/A	N/A	Parcial
Canais (stable/nightly)	Integrado	N/A	N/A	N/A
Override por projeto	rust-toolchain.toml	.nvmrc	.python-version	.sdkmanrc
Múltiplas versões	Sim	Sim	Sim	Sim
Gestão de ferramentas	Cargo install	npm -g	pip install	sdk install
Profiles	minimal/default/complete	N/A	N/A	N/A
Plataformas	Linux, macOS, Windows	Linux, macOS	Linux, macOS	Linux, macOS
Integração IDE	Excelente	Boa	Boa	Boa

O Rustup se destaca pela integração nativa com o ecossistema Rust, suporte a cross-compilation e gerenciamento de componentes — funcionalidades que são únicas entre gerenciadores de versão de linguagens.

Conclusão

O Rustup é uma ferramenta essencial que todo desenvolvedor Rust deve dominar. Ele simplifica enormemente o gerenciamento de versões do compilador, targets de cross-compilation e componentes adicionais.

Pontos-chave para lembrar:

rust-toolchain.toml garante consistência entre desenvolvedores
Canais (stable, beta, nightly) dão acesso a diferentes estágios do Rust
Cross-compilation com targets permite compilar para qualquer plataforma
Componentes como rust-analyzer e miri são instalados via rustup
Profiles otimizam a instalação para desenvolvimento ou CI

Para mais informações, consulte a documentação oficial do Rustup e o Rust Forge para calendário de releases.

Se você está começando, siga para o guia de instalação do Rust e aprenda a usar o Cargo. No próximo passo, conheça o Clippy para melhorar a qualidade do seu código Rust e entre na comunidade Rust Brasil para tirar dúvidas e acompanhar vagas.