cargo install: Instale CLIs Rust do crates.io | Rust Brasil

Use cargo install para compilar e instalar programas CLI escritos em Rust a partir do crates.io, de um repositório Git ou de um caminho local. O fluxo mínimo é simples: confirme que o Cargo já está no PATH, escolha a crate binária e execute o comando com --locked quando quiser reproduzir o lockfile publicado pela ferramenta.

cargo install --locked ripgrep
rg --version

Esse subcomando não instala o Cargo. Quem pesquisa cargo install muitas vezes mistura duas intenções: (1) colocar uma ferramenta Rust no PATH e (2) instalar a própria toolchain. A instalação do Cargo continua sendo responsabilidade do rustup e do guia de instalação do Cargo. Aqui o foco é o primeiro caso: distribuir e operar CLIs.

Resposta rápida: comandos essenciais

Confirme flags e defaults com cargo install --help na toolchain do ambiente. O comportamento pode variar entre versões do Cargo; pipelines devem piná-la junto com a versão da ferramenta instalada.

O que cargo install resolve de verdade

Em projetos Rust, há três caminhos comuns para obter um executável:

1. Desenvolvimento local — cargo run, cargo build --release dentro do repositório.
2. Distribuição empacotada — pacotes .deb, Homebrew, instaladores nativos, containers ou releases anexadas no GitHub.
3. cargo install — compilar a partir da fonte e copiar o binário para ~/.cargo/bin.

O terceiro caminho brilha para desenvolvedores, times internos e CI: a pessoa já tem Rust instalado, quer a ferramenta agora e aceita pagar o custo de compilação uma vez. É o padrão que aparece em quase todos os guias deste site quando falamos de cargo-audit, cargo-nextest, sqlx-cli, cargo-geiger ou cargo-zigbuild.

Para usuários finais sem toolchain Rust, cargo install raramente é a melhor UX. Nesse caso, prefira o fluxo de release engineering de binários, cross-compile com cargo-zigbuild e artefatos pré-compilados.

Pré-requisitos: Cargo, PATH e CARGO_HOME

Antes de qualquer instalação:

rustc --version
cargo --version
echo "$CARGO_HOME"
ls "${CARGO_HOME:-$HOME/.cargo}/bin"

Se cargo não existir, volte à instalação do Rust e ao rustup. Depois da primeira instalação da toolchain, o diretório ~/.cargo/bin precisa estar no PATH. No Linux e no macOS:

. "$HOME/.cargo/env"

No Windows, confirme %USERPROFILE%\.cargo\bin na variável Path do usuário e reabra o terminal.

CARGO_HOME controla onde ficam registros, git checkouts de dependências e o diretório bin/. Em CI é comum apontar CARGO_HOME para um cache persistente, o que também beneficia instalações repetidas de CLIs — combine com sccache quando o gargalo for recompilação do rustc.

Instalando do crates.io com segurança básica

A forma mais comum:

cargo install --locked cargo-audit
cargo audit --version

Boas práticas práticas:

• Prefira --locked quando a crate publica Cargo.lock utilizável. Isso aproxima a árvore de dependências daquela validada pelo mantenedor.
• Pine a versão em scripts e CI: cargo install --locked cargo-audit --version 0.21.2.
• Use --force com intenção, não por hábito. Ele sobrescreve o binário existente; útil para atualizar, perigoso se você não sabe qual versão estava em uso.
• Leia a página da crate no crates.io: features default, binários extras, requisitos de sistema (OpenSSL, protobuf, Zig) e plataforma suportada.

Exemplo com features explícitas, padrão recorrente em ferramentas de banco e TLS:

cargo install sqlx-cli \
  --locked \
  --no-default-features \
  --features rustls,postgres

Esse padrão evita compilar backends que o time não usa e reduz tempo de build. O mesmo cuidado aparece no guia de migrations SQLx.

--git, --path, branches e workspaces

A partir de Git

cargo install --locked \
  --git https://github.com/example/ferramenta \
  --tag v1.4.0 \
  --bin ferramenta

Use tag ou commit sempre que o binário alimentar CI, imagem Docker ou estação compartilhada. Branch móvel (main) é aceitável para experimentação, péssima para reproducibilidade.

Em monorepos, combine --git com -p / --bin conforme a ajuda da sua versão do Cargo e a estrutura do workspace. Se a instalação falhar por pacote ambíguo, clone o repositório e use --path no crate certo.

A partir de um caminho local

cargo install --path ./crates/minha-cli --locked

Esse modo é excelente para:

• validar a UX de instalação da própria CLI antes do publish;
• distribuir ferramentas internas sem crates.io;
• testar um bugfix local sem publicar versão intermediária.

Lembre que --path instala o estado atual do working tree. Commits limpos e tags internas evitam o clássico “na minha máquina a CLI estava certa”.

Escolhendo binários, targets e perfil

Nem toda crate publica um único binário. Algumas expõem vários [[bin]]. Nesses casos:

cargo install --locked minha-crate --bin ferramenta-a
cargo install --locked minha-crate --bin ferramenta-b

Para cross-install em outro target, a história fica mais complexa: além de --target, você precisa do linker e, muitas vezes, de headers C. Para binários Linux musl a partir de macOS ou Ubuntu, o caminho mais curto em 2026 costuma ser gerar o artefato com cargo-zigbuild e distribuir o binário pronto, em vez de exigir que cada usuário rode cargo install com target estrangeiro.

O perfil padrão de cargo install já busca um build de release da ferramenta. Ainda assim, crates grandes sofrem com tempo de compilação e tamanho final. Se a CLI instalada ficar pesada, as técnicas de cargo-bloat e linkagem rápida com mold ajudam quem mantém a ferramenta — menos quem só consome o binário.

Atualizar, listar e remover

cargo install --list
cargo install --locked --force ripgrep
cargo uninstall ripgrep

cargo install --list mostra o que está sob o CARGO_HOME atual. Em máquinas com múltiplos CARGO_HOME (CI, containers, toolchains por projeto), a lista muda. Documente qual ambiente cada pipeline usa.

Política saudável para times:

1. manter um arquivo dev-tools.txt ou script scripts/bootstrap-tools.sh com crates e versões;
2. atualizar em lote sob revisão, não sob demanda silenciosa;
3. preferir actions/orbs oficiais ou binários versionados quando a ferramenta for crítica de segurança.

Para auditoria do que uma ferramenta traz no grafo, combine a instalação com cargo-tree, cargo-audit e a política descrita em cargo-deny e SBOM.

cargo install em CI e Docker

Em GitHub Actions, o padrão mínimo é:

- name: Install cargo-nextest
  run: cargo install --locked cargo-nextest --version 0.9.95

- name: Run tests
  run: cargo nextest run --workspace

Melhorias importantes:

• Cache de CARGO_HOME para não recompilar a CLI em todo job.
• Pin de versão da ferramenta e da toolchain (dtolnay/rust-toolchain ou equivalente).
• Evitar cargo install dentro do loop crítico se um binário pré-compilado oficial existir (muitas tools publicam releases).
• Separar a camada de ferramentas em Docker com cargo-chef ou uma imagem base interna que já contenha cargo-audit, sqlx-cli e cargo-nextest.

Exemplo de bootstrap idempotente:

#!/usr/bin/env bash
set -euo pipefail

need() {
  local crate="$1"
  local version="$2"
  if ! command -v "$crate" >/dev/null 2>&1; then
    cargo install --locked "$crate" --version "$version"
  fi
}

need cargo-audit 0.21.2
need cargo-nextest 0.9.95

Ajuste o nome do binário quando ele diferir do nome da crate (ripgrep instala rg).

Erros frequentes e como ler a mensagem

cargo: command not found depois do install

Quase sempre PATH. O binário foi para ~/.cargo/bin, mas a sessão atual não enxerga o diretório. Abra um terminal novo ou carregue env.

Falha ao compilar dependência nativa (OpenSSL, libclang, protobuf)

A crate precisa de toolchain C/C++ ou libs do sistema. Leia o README da ferramenta: muitas oferecem feature vendored-openssl ou bins pré-compilados. O guia de cargo-geiger mostra exatamente esse tipo de escape hatch.

Conflito de versão / binário já existe

Use --force para sobrescrever, ou cargo uninstall antes. Em CI, prefira sempre a mesma versão pinada para o job inteiro.

Workspace ou pacote ambíguo

Especifique --path, --bin ou o pacote correto. Em monorepos, consulte também o guia de workspaces Cargo.

Instalação lenta demais

• ative cache de CARGO_HOME;
• use sccache;
• prefira linker rápido no host que compila a ferramenta;
• considere baixar release pronta em vez de compilar na hora.

Quando não usar cargo install

Evite empurrar cargo install como único canal de distribuição quando:

• o público-alvo não tem Rust instalado;
• a compilação exige sysroot complexo ou demora dezenas de minutos;
• a ferramenta é controlada por compliance e precisa de artefato assinado;
• você precisa do mesmo binário em deploys imutáveis sem compilador.

Nesses cenários, publique releases, containers ou pacotes de sistema. cargo install continua excelente para quem desenvolve em Rust e para bootstraps internos — não para substituir um instalador de produto.

Se a CLI for construída com Clap, documente no README os dois caminhos: cargo install --locked sua-cli para devs e download do binário para demais usuários.

Checklist prático

• Confirmei que a intenção é instalar uma CLI, não o Cargo.
• cargo --version funciona e ~/.cargo/bin está no PATH.
• Usei --locked e, em scripts, pinei --version.
• Revisei features default e desativei o que não precisamos.
• Em Git, fixei tag/commit; em path, parti de working tree limpa.
• Testei o binário (ferramenta --version / --help).
• Documentei atualização e remoção para o time.
• Em CI, cacheei CARGO_HOME e evitei reinstalações desnecessárias.
• Para distribuição ampla, planejei artefato pré-compilado além do cargo install.

Conclusão

cargo install é o atalho padrão do ecossistema Rust para colocar uma CLI no PATH a partir do código-fonte. Ele resolve o dia a dia de quem já usa Cargo: auditar dependências, rodar nextest, gerar migrations, expandir macros e cross-compilar.

A diferença entre um bootstrap frágil e um fluxo profissional está nos detalhes: --locked, versão pinada, PATH correto, features mínimas, cache em CI e honestidade sobre quando um binário pré-compilado serve melhor. Com isso, o mesmo comando que instala ripgrep em um notebook passa a sustentar o tooling do time sem surpresas.

Comece instalando uma ferramenta que você já usa na documentação interna, registre a versão no script de bootstrap e só então replique o padrão na CI. Quando cargo install --list refletir exatamente o conjunto homologado pelo time, a cadeia de CLIs deixa de ser folklore e vira parte reproduzível do ambiente Rust.