Como instalar o Cargo?

Instale o Rust pelo rustup, pois o Cargo é incluído automaticamente. No Linux e macOS, execute o instalador oficial do rustup; no Windows, baixe e execute rustup-init.exe. Depois, abra um novo terminal e confirme com cargo --version.

O comando cargo install instala o Cargo?

Não. cargo install instala programas binários publicados como crates, por exemplo ripgrep ou cargo-watch. Para instalar o próprio Cargo, use o rustup, que instala Rust, rustc e Cargo juntos.

Como corrigir cargo: command not found?

Abra um novo terminal e confirme se a pasta .cargo/bin está no PATH. No Linux e macOS, carregue o arquivo $HOME/.cargo/env. No Windows, confira se %USERPROFILE%\.cargo\bin está na variável Path do usuário.

Cargo funciona sem o Rust instalado?

Na prática, não para o fluxo normal de desenvolvimento. Cargo chama o compilador rustc para construir projetos, por isso a instalação recomendada e suportada é manter Rust, Cargo e rustup na mesma toolchain.

Como Instalar Cargo no Windows, Linux e macOS

Para instalar o Cargo, instale o Rust com o rustup: o Cargo vem incluído automaticamente no Windows, Linux e macOS. Depois, abra um novo terminal e execute cargo --version. Não use cargo install para instalar o próprio Cargo — esse subcomando serve para instalar programas publicados como crates, como ripgrep e cargo-watch.

Sistema	Instalação recomendada	Verificação
Linux	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh`	`cargo --version`
macOS	Mesmo instalador do `rustup` usado no Linux	`cargo --version`
Windows	Baixar e executar `rustup-init.exe` em rustup.rs	`cargo --version` no PowerShell

Se você já tem o Cargo funcionando e quer aprender Cargo.toml, workspaces, features e otimização de builds, consulte a referência principal sobre Cargo no ecossistema Rust. Esta página prioriza instalação, PATH, cargo install e solução de problemas, evitando competir com o guia conceitual.

Como instalar Cargo com rustup

Linux e macOS

No terminal, execute o instalador oficial:

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

Escolha a instalação padrão quando o assistente perguntar. Em seguida, abra um novo terminal ou carregue o ambiente na sessão atual:

. "$HOME/.cargo/env"

Confirme que Rust, Cargo e rustup estão disponíveis:

rustc --version
cargo --version
rustup --version

No macOS, a primeira compilação também pode solicitar as Command Line Tools do Xcode. Instale-as com xcode-select --install se o linker não estiver disponível.

Windows

Acesse rustup.rs, baixe rustup-init.exe e execute o instalador. O fluxo padrão instala a toolchain estável e adiciona %USERPROFILE%\.cargo\bin ao Path do usuário. Feche e abra novamente o PowerShell ou o Windows Terminal antes de verificar:

rustc --version
cargo --version
rustup --version

Se o instalador pedir ferramentas de compilação, instale o Visual Studio Build Tools com a carga de trabalho Desenvolvimento para Desktop com C++. Isso fornece linker e bibliotecas exigidos pela toolchain MSVC padrão.

Teste rápido após a instalação

Não pare na impressão da versão. Crie e execute um projeto mínimo para validar compilador, Cargo, linker e PATH de uma vez:

cargo new ola-cargo
cd ola-cargo
cargo run

A saída deve terminar com Hello, world!. Se esse teste funcionar, a instalação está pronta para os primeiros passos com Rust.

`cargo install` não instala o Cargo

A consulta cargo install costuma misturar duas intenções. O Cargo em si é instalado pelo rustup. Já o comando cargo install NOME baixa o código de uma crate que fornece binário, compila em modo release e coloca o executável em ~/.cargo/bin — ou em %USERPROFILE%\.cargo\bin no Windows.

cargo install ripgrep
cargo install cargo-watch
cargo install cargo-nextest --locked
cargo install --list

Use --locked quando quiser respeitar o Cargo.lock publicado pelo projeto. Antes de instalar uma ferramenta desconhecida, confira o repositório, a manutenção e a origem da crate no crates.io.

Primeiros Comandos

Criar um Novo Projeto

# Criar um binário (aplicação)
cargo new meu-app
cd meu-app

# Criar uma biblioteca
cargo new minha-lib --lib

# Inicializar em um diretório existente
cargo init
cargo init --lib

Estrutura de um Projeto Cargo

meu-app/
├── Cargo.toml       # Manifesto do projeto
├── Cargo.lock       # Lock de dependências (commitado para binários)
├── src/
│   ├── main.rs      # Ponto de entrada (binários)
│   └── lib.rs       # Ponto de entrada (bibliotecas)
├── tests/           # Testes de integração
├── benches/         # Benchmarks
├── examples/        # Exemplos
└── target/          # Artefatos de compilação

Build, Run e Test

# Compilar em modo debug
cargo build

# Compilar em modo release (otimizado)
cargo build --release

# Compilar e executar
cargo run

# Executar com argumentos
cargo run -- arg1 arg2

# Verificar erros sem compilar (mais rápido)
cargo check

# Executar testes
cargo test

# Executar testes com saída visível
cargo test -- --nocapture

# Executar um teste específico
cargo test nome_do_teste

Cargo.toml: O Manifesto

O Cargo.toml define tudo sobre seu projeto. Para uma explicação aprofundada sobre manifesto, lockfile e o papel do build system, veja também o que é Cargo no Rust:

[package]
name = "meu-app"
version = "0.1.0"
edition = "2024"
authors = ["Seu Nome <email@exemplo.com>"]
description = "Descrição do projeto"
license = "MIT"
repository = "https://github.com/usuario/meu-app"

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
reqwest = "0.12"

[dev-dependencies]
criterion = "0.5"
tempfile = "3"

[build-dependencies]
cc = "1.0"

[[bin]]
name = "meu-app"
path = "src/main.rs"

Gerenciar Dependencias

# Adicionar uma dependência
cargo add serde
cargo add serde --features derive
cargo add tokio -F full

# Adicionar como dev-dependency
cargo add criterion --dev

# Remover uma dependência
cargo remove serde

# Atualizar dependências
cargo update

# Atualizar uma dependência específica
cargo update -p serde

# Ver árvore de dependências
cargo tree

# Ver dependências desatualizadas
cargo install cargo-outdated
cargo outdated

Features

Features permitem compilação condicional de funcionalidades:

[features]
default = ["json"]
json = ["dep:serde_json"]
xml = ["dep:quick-xml"]
full = ["json", "xml"]

[dependencies]
serde_json = { version = "1.0", optional = true }
quick-xml = { version = "0.31", optional = true }

Usar features:

# Compilar com features padrão
cargo build

# Compilar sem features padrão
cargo build --no-default-features

# Compilar com features específicas
cargo build --features "json,xml"

# Compilar com todas as features
cargo build --all-features

Profiles de Compilação

Profiles controlam as otimizações do compilador:

# Cargo.toml

# Profile de desenvolvimento (cargo build)
[profile.dev]
opt-level = 0
debug = true
overflow-checks = true

# Profile de release (cargo build --release)
[profile.release]
opt-level = 3
lto = true
codegen-units = 1
strip = true
panic = "abort"

# Profile customizado para testes
[profile.test]
opt-level = 1

# Profile customizado para benchmarks
[profile.bench]
opt-level = 3
lto = true

# Usar profile de release
cargo build --release

# O binário release fica em:
# target/release/meu-app (muito menor e mais rápido)

Para entender como builds release funcionam em CI, consulte o guia de GitHub Actions.

Workspaces

Workspaces permitem gerenciar múltiplos crates em um único repositório:

# Cargo.toml (raiz)
[workspace]
members = [
    "crates/core",
    "crates/api",
    "crates/cli",
]
resolver = "2"

[workspace.package]
version = "0.1.0"
edition = "2024"
authors = ["Equipe <team@example.com>"]

[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

Em cada crate do workspace:

# crates/api/Cargo.toml
[package]
name = "meu-app-api"
version.workspace = true
edition.workspace = true

[dependencies]
serde.workspace = true
meu-app-core = { path = "../core" }

Comandos para workspaces:

# Build de todo o workspace
cargo build --workspace

# Testar todo o workspace
cargo test --workspace

# Build de um crate específico
cargo build -p meu-app-api

# Executar o binário CLI
cargo run -p meu-app-cli

Documentação

O Cargo gera documentação a partir dos doc comments:

# Gerar documentação
cargo doc

# Gerar e abrir no navegador
cargo doc --open

# Incluir dependências na documentação
cargo doc --document-private-items

# Gerar documentação do workspace
cargo doc --workspace

Publicar Crates

Para publicar no crates.io:

# Login (necessário uma vez)
cargo login seu-token-aqui

# Verificar antes de publicar
cargo publish --dry-run

# Publicar
cargo publish

# Publicar em um workspace (crate específico)
cargo publish -p minha-lib

Checklist antes de publicar:

Preencher [package] no Cargo.toml (name, version, description, license)
Incluir um README.md
Verificar com cargo clippy e cargo test
Rodar cargo publish --dry-run

cargo install

Para instalar binários de crates publicados:

# Instalar um binário
cargo install ripgrep
cargo install fd-find
cargo install cargo-watch

# Instalar de um repositório git
cargo install --git https://github.com/usuario/repo

# Instalar versão específica
cargo install ripgrep --version 14.0.0

# Listar binários instalados
cargo install --list

# Desinstalar
cargo uninstall ripgrep

Os binários são instalados em ~/.cargo/bin/.

Ferramentas Úteis via Cargo

# Recompilação automática ao salvar
cargo install cargo-watch
cargo watch -x run
cargo watch -x test

# Auditoria de segurança
cargo install cargo-audit
cargo audit

# Expansão de macros
cargo install cargo-expand
cargo expand

# Verificar código não utilizado
cargo install cargo-udeps --locked
cargo +nightly udeps

# Binários mais rápidos para instalar
cargo install cargo-binstall
cargo binstall ripgrep

Configuração Global

Crie ~/.cargo/config.toml para configurações globais:

[build]
# Usar mais jobs de compilação
jobs = 8

[target.x86_64-unknown-linux-gnu]
# Usar linker mais rápido
linker = "clang"
rustflags = ["-C", "link-arg=-fuse-ld=mold"]

[net]
# Configurar proxy
# proxy = "http://proxy:8080"

[registries.crates-io]
protocol = "sparse"

[alias]
b = "build"
r = "run"
t = "test"
c = "check"
cl = "clippy"

Solução de Problemas

`cargo: command not found` no Linux ou macOS

Primeiro, carregue o ambiente criado pelo rustup:

. "$HOME/.cargo/env"
which cargo
cargo --version

Se isso resolver, abra um novo terminal. Se não resolver, confirme que $HOME/.cargo/bin faz parte do PATH. Evite instalar uma segunda cópia do Cargo pelo gerenciador de pacotes da distribuição, pois misturar versões do sistema com rustup pode tornar a toolchain difícil de diagnosticar.

`cargo` não é reconhecido no Windows

Feche e abra o terminal após instalar o rustup. Em seguida, verifique se %USERPROFILE%\.cargo\bin aparece em Configurações do Sistema > Variáveis de Ambiente > Path. No PowerShell, você pode inspecionar o caminho com:

$env:Path -split ';'
Get-Command cargo

Se cargo.exe for encontrado, mas o build falhar com erro de linker, instale ou repare o Visual Studio Build Tools em vez de reinstalar o Cargo.

Compilação lenta

Use um linker rápido (mold, lld ou zld) e habilite compilação incremental:

# Instalar mold (Linux)
sudo apt install mold  # ou equivalente

# Verificar compilação incremental
echo $CARGO_INCREMENTAL  # deve ser 1 ou não definido

Erro: “failed to select a version for the requirement”

Conflito de dependências. Verifique com:

cargo tree -d  # Mostra duplicatas
cargo update   # Tenta resolver

Cache do Cargo corrompido

# Limpar cache de build
cargo clean

# Limpar cache de registro
rm -rf ~/.cargo/registry/cache/
cargo fetch

Próximos Passos

Com o Cargo dominado:

Siga o tutorial de Primeiros Passos com Rust
Consulte o Cheatsheet Rust para referência rápida
Aprenda a gerenciar toolchains com o Guia Completo do Rustup
Configure seu editor com o guia de VS Code ou Neovim
Veja as Perguntas Frequentes para dúvidas comuns

Se você também usa build systems em outras linguagens, confira o golang.com.br para comparar o Cargo com o Go modules.

Última atualização: 7 de agosto de 2026. Para remover o Cargo e o Rust, veja Como Desinstalar Rust.

Como Instalar Cargo no Windows, Linux e macOS | Rust Brasil