--- title: "cargo install: Instale CLIs Rust do crates.io | Rust Brasil" url: "https://rustlang.com.br/blog/cargo-install-clis-rust-crates-io-2026/" markdown_url: "https://rustlang.com.br/blog/cargo-install-clis-rust-crates-io-2026.MD" description: "Aprenda cargo install em Rust: instale CLIs do crates.io com --locked, --git, --path e --force. Guia de PATH, features, CI, atualização e remoção segura." date: "2026-08-25" author: "Equipe Rust Brasil" --- # cargo install: Instale CLIs Rust do crates.io | Rust Brasil Aprenda cargo install em Rust: instale CLIs do crates.io com --locked, --git, --path e --force. Guia de PATH, features, CI, atualização e remoção segura. **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](/ecossistema/cargo/) já está no PATH, escolha a crate binária e execute o comando com `--locked` quando quiser reproduzir o lockfile publicado pela ferramenta. ```bash 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](/ecossistema/rustup/) e do guia de [instalação do Cargo](/instalacao/cargo/). Aqui o foco é o primeiro caso: distribuir e operar CLIs. ## Resposta rápida: comandos essenciais | Objetivo | Comando | |---|---| | Instalar do crates.io | `cargo install --locked nome-da-crate` | | Ver opções da versão local | `cargo install --help` | | Instalar versão específica | `cargo install --locked nome-da-crate --version 1.2.3` | | Forçar reinstalação/atualização | `cargo install --locked --force nome-da-crate` | | Instalar de Git | `cargo install --locked --git https://github.com/org/repo` | | Instalar de caminho local | `cargo install --path ./crates/minha-cli` | | Escolher o binário em um pacote | `cargo install --locked nome-da-crate --bin nome-do-binario` | | Ativar features | `cargo install --locked nome-da-crate --features feature_a,feature_b` | | Listar instalados | `cargo install --list` | | Remover um binário instalado | `cargo uninstall nome-da-crate` | 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](/blog/rust-release-engineering-binaries-cli-servicos-2026/), cross-compile com [cargo-zigbuild](/blog/cargo-zigbuild-cross-compile-rust-2026/) e artefatos pré-compilados. ## Pré-requisitos: Cargo, PATH e CARGO_HOME Antes de qualquer instalação: ```bash rustc --version cargo --version echo "$CARGO_HOME" ls "${CARGO_HOME:-$HOME/.cargo}/bin" ``` Se `cargo` não existir, volte à [instalação do Rust](/instalacao/) e ao [rustup](/ecossistema/rustup/). Depois da primeira instalação da toolchain, o diretório `~/.cargo/bin` precisa estar no PATH. No Linux e no macOS: ```bash . "$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](/blog/sccache-rust-cache-compilacao-ci-2026/) quando o gargalo for recompilação do `rustc`. ## Instalando do crates.io com segurança básica A forma mais comum: ```bash 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: ```bash 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](/blog/sqlx-migrations-rust-postgresql-ci-deploy-2026/). ## `--git`, `--path`, branches e workspaces ### A partir de Git ```bash 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 ```bash 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: ```bash 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](/blog/cargo-zigbuild-cross-compile-rust-2026/) 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](/blog/cargo-bloat-reduzir-tamanho-binario-rust-2026/) e linkagem rápida com [mold](/blog/mold-linker-rust-compilacao-rapida-2026/) ajudam quem mantém a ferramenta — menos quem só consome o binário. ## Atualizar, listar e remover ```bash 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](/blog/cargo-tree-grafo-dependencias-rust-2026/), [cargo-audit](/blog/cargo-audit-vulnerabilidades-dependencias-rust-ci-2026/) e a política descrita em [cargo-deny e SBOM](/blog/rust-seguranca-supply-chain-cargo-deny-sbom-2026/). ## `cargo install` em CI e Docker Em GitHub Actions, o padrão mínimo é: ```yaml - 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](/blog/cargo-chef-cache-docker-rust-2026/) ou uma imagem base interna que já contenha `cargo-audit`, `sqlx-cli` e `cargo-nextest`. Exemplo de bootstrap idempotente: ```bash #!/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](/blog/cargo-geiger-unsafe-rust-dependencias-2026/) 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](/blog/cargo-workspaces-monorepos-rust-2026/). ### 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](/tutoriais/cli-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.