---
title: "cargo-msrv: Versão Mínima do Rust na CI | Rust Brasil"
url: "https://rustlang.com.br/blog/cargo-msrv-versao-minima-rust-ci-2026/"
markdown_url: "https://rustlang.com.br/blog/cargo-msrv-versao-minima-rust-ci-2026.MD"
description: "Use cargo-msrv para descobrir e verificar a versão mínima do Rust suportada pelo projeto. Guia com rust-version, features, workspace, CI e boas práticas."
date: "2026-08-09"
author: "Equipe Rust Brasil"
---

# cargo-msrv: Versão Mínima do Rust na CI | Rust Brasil

Use cargo-msrv para descobrir e verificar a versão mínima do Rust suportada pelo projeto. Guia com rust-version, features, workspace, CI e boas práticas.


**Para descobrir a versão mínima do Rust suportada por um projeto, instale `cargo-msrv` e rode `cargo msrv find`; depois declare o resultado em `rust-version` no `Cargo.toml` e use `cargo msrv verify` na CI.** Esse fluxo transforma a MSRV — *Minimum Supported Rust Version* — de uma promessa informal em uma compatibilidade testada.

A MSRV importa principalmente para bibliotecas, CLIs distribuídas a muitos ambientes, ferramentas usadas em distribuições Linux e projetos corporativos que não atualizam a toolchain imediatamente. Sem uma política explícita, uma dependência pode adotar um recurso recente da linguagem e quebrar usuários que continuam em um compilador mais antigo, mesmo que a API pública do seu crate não tenha mudado.

Este guia mostra como usar `cargo-msrv`, interpretar o resultado, declarar `rust-version`, lidar com features e workspaces, evitar falsos resultados e montar uma verificação de CI que não fica presa ao acaso do `Cargo.lock`.

## Resposta rápida: o fluxo recomendado

| Etapa | Comando ou configuração | Objetivo |
|---|---|---|
| Instalar a ferramenta | `cargo install cargo-msrv --locked` | Disponibilizar o subcomando |
| Descobrir a versão mínima | `cargo msrv find` | Testar toolchains candidatas |
| Declarar a política | `rust-version = "1.xx"` | Informar Cargo e consumidores |
| Confirmar o resultado | `cargo msrv verify` | Verificar a versão declarada |
| Testar recursos opcionais | `cargo msrv find -- --all-features` | Cobrir a combinação documentada |
| Automatizar | job com a toolchain MSRV | Impedir regressões na CI |

Antes de copiar os comandos para um pipeline crítico, consulte `cargo msrv --help` e o help do subcomando instalado. Flags podem evoluir entre versões; por isso, vale fixar a versão da ferramenta na CI quando a reprodutibilidade for requisito.

## O que é MSRV em Rust

MSRV é a sigla para **Minimum Supported Rust Version**: a versão mais antiga do compilador que o projeto pretende suportar. Se um crate declara MSRV 1.78, por exemplo, a expectativa é que a configuração suportada compile com Rust 1.78, além das versões estáveis posteriores dentro da política do projeto.

Isso não significa que todo código possível atrás de qualquer feature experimental precise funcionar nessa versão. A equipe deve definir o contrato:

- apenas as features padrão;
- todas as features públicas;
- combinações específicas por target;
- biblioteca sem exemplos e ferramentas auxiliares;
- workspace inteiro ou somente os crates publicados.

Uma declaração sem esse escopo é ambígua. A versão mínima pode funcionar para `cargo check`, mas falhar em testes, exemplos, build scripts ou em uma feature de TLS ativada por consumidores.

O campo oficial fica no `Cargo.toml`:

```toml
[package]
name = "minha-biblioteca"
version = "0.4.0"
edition = "2021"
rust-version = "1.78"
```

O `rust-version` permite que o Cargo rejeite cedo uma toolchain incompatível, em vez de deixar o usuário enfrentar dezenas de erros de sintaxe ou de biblioteca padrão. Ele também comunica a intenção para ferramentas, mantenedores de distribuições e automações.

## Por que a versão mínima quebra sem ninguém perceber

A maior parte dos times desenvolve e testa com o Rust estável mais recente. Nesse ambiente, uma mudança aparentemente inocente pode elevar a MSRV:

- uso de uma API da biblioteca padrão estabilizada recentemente;
- sintaxe nova da linguagem;
- mudança da edition ou de comportamento do Cargo;
- atualização de dependência cujo novo release exige Rust mais recente;
- ativação de uma feature transitiva com MSRV maior;
- build script que passou a usar uma API nova;
- exemplo ou teste que compila apenas na toolchain atual.

O problema pode permanecer invisível até a publicação. O mantenedor executa `cargo test` com Rust atual, publica o crate, e só então um consumidor em uma distribuição conservadora recebe um erro.

Essa compatibilidade é diferente da compatibilidade de API analisada pelo [cargo-semver-checks](/blog/cargo-semver-checks-rust-api-ci-2026/). Uma release pode preservar todos os tipos e métodos públicos e, ainda assim, quebrar consumidores porque passou a exigir um compilador mais novo.

## Instalando e executando cargo-msrv

Instale a ferramenta pelo Cargo:

```bash
cargo install cargo-msrv --locked
cargo msrv --version
```

Na raiz de um projeto com `Cargo.toml`, inicie a busca:

```bash
cargo msrv find
```

Em termos conceituais, a ferramenta testa versões candidatas do compilador até localizar a mais antiga que satisfaz o critério de compilação. Ela pode instalar ou usar toolchains por meio do ecossistema `rustup`, então a primeira execução tende a ser mais lenta e consumir espaço em disco.

Depois de declarar `rust-version`, confirme a política:

```bash
cargo msrv verify
```

A divisão é útil:

- **`find`** responde “qual parece ser a versão mínima hoje?”;
- **`verify`** responde “a versão que declaramos ainda funciona?”.

Não rode `find` em toda pull request se o projeto for grande. A busca testa múltiplas toolchains e pode ser cara. Descubra a baseline localmente ou em um job manual; na CI cotidiana, teste diretamente a versão declarada e use `verify` em releases ou em uma rotina agendada.

## Como o cargo-msrv encontra a versão

Uma busca ingênua poderia testar todas as releases do Rust uma por uma. Ferramentas de MSRV procuram reduzir esse trabalho escolhendo versões candidatas de forma mais eficiente e executando um comando Cargo para decidir se cada candidata passa ou falha.

O resultado, porém, depende do que foi testado. Pergunte sempre:

1. qual comando Cargo foi executado;
2. quais features estavam ativas;
3. qual target foi usado;
4. qual `Cargo.lock` estava presente;
5. se o workspace inteiro entrou no teste;
6. se exemplos, testes e build scripts foram compilados.

O número encontrado não é uma propriedade metafísica do código. Ele é o resultado de uma **configuração reproduzível**. Se você roda apenas com features padrão, encontrou a MSRV das features padrão. Se publica suporte a `serde`, TLS ou banco de dados como features opcionais, precisa testar essas combinações também.

## Testando features e targets

O `cargo-msrv` aceita argumentos destinados ao Cargo após `--`. Um cenário comum é investigar todas as features:

```bash
cargo msrv find -- --all-features
cargo msrv verify -- --all-features
```

Para um pacote específico do workspace:

```bash
cargo msrv find -- -p minha-biblioteca
```

E para considerar mais targets Cargo:

```bash
cargo msrv verify -- --all-targets
```

Confirme a sintaxe na versão instalada. O ponto operacional é separar a configuração da ferramenta dos argumentos encaminhados ao Cargo.

### Cuidado com `--all-features`

Todas as features ao mesmo tempo nem sempre representam uma configuração válida. Alguns projetos mantêm backends mutuamente exclusivos, como duas implementações de TLS ou dois bancos de dados. Nesse caso, crie uma matriz explícita:

```text
features padrão
--no-default-features
--features serde
--features rustls
--features native-tls
```

Documente qual delas define a MSRV oficial. Se uma feature opcional exige compilador mais recente, há três caminhos honestos:

1. elevar a MSRV do projeto inteiro;
2. manter a feature fora do contrato de MSRV e documentar isso;
3. ajustar a implementação ou a versão da dependência para preservar o suporte.

Não esconda a diferença. Consumidores precisam saber se `default-features = false` ou uma feature específica muda o requisito de toolchain.

## Dependências são parte da sua MSRV

Seu código pode compilar com Rust antigo enquanto uma dependência recém-atualizada não compila. Por isso, a MSRV efetiva pertence ao conjunto:

```text
código + Cargo.toml + features + target + resolução de dependências
```

O `Cargo.lock` muda bastante a análise:

- **aplicações e CLIs** normalmente versionam o lockfile; testar com ele representa o produto entregue;
- **bibliotecas** são resolvidas no grafo do consumidor; passar apenas com um lockfile antigo pode esconder que a resolução mais nova elevou a MSRV.

Para bibliotecas, vale testar duas perguntas separadas:

1. a versão mínima compila com a resolução controlada pelo lockfile do repositório?
2. a política continua válida quando dependências compatíveis recebem novos releases?

O Cargo e o ecossistema têm mecanismos para declarar requisitos de versão, mas mantenedores ainda precisam revisar atualizações. Ferramentas de limpeza como [cargo-machete e cargo-udeps](/blog/cargo-machete-cargo-udeps-dependencias-nao-usadas-2026/) resolvem outro problema: dependências mortas. Para MSRV, até uma dependência legítima e usada pode ser a responsável pelo aumento.

Use estes comandos durante o diagnóstico:

```bash
cargo tree
cargo tree -e features
cargo update -p nome-da-crate --precise x.y.z
```

O último comando é útil para um experimento local com uma versão específica, não como solução permanente sem entender segurança, correções e política de atualização.

## MSRV em workspaces

Em um workspace, cada pacote pode ter necessidades diferentes. Uma biblioteca central pode prometer suporte amplo, enquanto uma CLI administrativa usa o Rust mais recente.

Exemplo com configuração centralizada:

```toml
[workspace]
members = ["crates/core", "crates/cli"]
resolver = "2"

[workspace.package]
edition = "2021"
rust-version = "1.78"
```

Nos membros que herdam a configuração:

```toml
[package]
name = "core"
version = "0.3.0"
edition.workspace = true
rust-version.workspace = true
```

Centralizar evita divergência acidental, mas só faz sentido se os pacotes realmente compartilham o mesmo contrato. Se a CLI pode avançar mais rápido que a biblioteca publicada, declare políticas separadas e teste cada pacote com `-p`.

Para organização de repositórios maiores, veja o guia de [Cargo workspaces e monorepos](/blog/cargo-workspaces-monorepos-rust-2026/).

## Configurando uma CI de MSRV

A verificação mais transparente é instalar diretamente a toolchain mínima declarada e executar o comando que representa o contrato do projeto.

Exemplo para GitHub Actions:

```yaml
name: msrv

on:
  pull_request:
  push:
    branches: [main]

jobs:
  msrv:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Instalar a toolchain mínima
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: "1.78"

      - name: Verificar biblioteca e features
        run: cargo check --locked --all-targets --all-features
```

Para um projeto com matriz de features:

```yaml
strategy:
  matrix:
    cargo_args:
      - "--locked"
      - "--locked --no-default-features"
      - "--locked --no-default-features --features serde"

steps:
  - uses: actions/checkout@v4
  - uses: dtolnay/rust-toolchain@master
    with:
      toolchain: "1.78"
  - run: cargo check ${{ matrix.cargo_args }}
```

Na prática, mantenha dois tipos de job:

| Job | Frequência | Função |
|---|---|---|
| Toolchain MSRV fixa | toda pull request | Detectar regressão imediatamente |
| `cargo msrv verify` ou `find` | semanal, manual ou release | Auditar declaração e investigar redução |

Fixar a toolchain diretamente torna o erro fácil de reproduzir. O `cargo-msrv` complementa o processo ao descobrir e validar a baseline. O guia de [CI/CD para Rust](/artigos/ci-cd-rust/) cobre os demais checks do pipeline.

## MSRV e SemVer

A comunidade Rust não aplica uma única regra universal para aumentar MSRV. Alguns projetos tratam qualquer aumento como mudança incompatível; outros permitem aumentos em releases menores, desde que documentados; outros mantêm uma janela, como “as N versões estáveis mais recentes”.

O importante é publicar uma política previsível. Um trecho de README pode dizer:

> A MSRV é Rust 1.78. Aumentos serão destacados nas notas de release e poderão ocorrer em versões menores quando necessários por correções de segurança ou dependências essenciais.

Para bibliotecas muito usadas, considere uma política mais conservadora. Para aplicativos controlados pela própria equipe, a MSRV pode ter menos valor, porque o deploy já fixa uma toolchain. Mesmo assim, `rust-version` continua útil para mensagens de erro claras e builds reproduzíveis.

Ao preparar uma publicação, combine a revisão de MSRV com [cargo-semver-checks](/blog/cargo-semver-checks-rust-api-ci-2026/) e o checklist de [release engineering em Rust](/blog/rust-release-engineering-binaries-cli-servicos-2026/). Eles cobrem camadas diferentes do contrato entregue.

## Falsos resultados e erros comuns

### Encontrar uma versão baixa demais

Isso acontece quando o comando testado não compila features, exemplos ou targets que fazem parte do suporte real. A correção é ampliar a matriz, não aceitar o número automaticamente.

### Encontrar uma versão alta demais

Pode ser uma dependência transitiva recente, uma ferramenta auxiliar dentro do workspace ou um lockfile atualizado. Isole pacotes e features antes de elevar a declaração.

### Testar apenas `cargo check`

`check` é rápido, mas uma biblioteca com código específico em testes, exemplos ou build scripts pode falhar em `cargo test` ou `cargo build`. Defina qual nível de validação cabe na CI e rode uma auditoria mais ampla antes de releases.

### Manter `rust-version` desatualizado

Se a CI testa apenas stable, o campo pode virar ficção. O job da toolchain mínima precisa ser obrigatório para mudanças que afetam código, manifesto ou lockfile.

### Confundir MSRV com edition

A Rust edition define um conjunto de regras de linguagem e migração; a MSRV define a versão mínima do compilador. Elas se relacionam, mas não são a mesma coisa. Um projeto na edition 2021 pode escolher uma MSRV posterior ao primeiro compilador que suportou essa edition.

### Prometer suporte eterno

Quanto mais antiga a MSRV, maior o custo de manutenção e menor o acesso a melhorias da linguagem e do ecossistema. Compatibilidade é um produto: mantenha-a quando ela beneficia usuários reais, não apenas para exibir um número baixo.

## Checklist para adotar MSRV

- [ ] definir quem precisa de uma toolchain antiga e por quê;
- [ ] escolher o escopo: defaults, todas as features ou matriz documentada;
- [ ] instalar `cargo-msrv` e rodar `cargo msrv find`;
- [ ] confirmar o resultado com build e testes relevantes;
- [ ] declarar `rust-version` no `Cargo.toml`;
- [ ] adicionar um job com a toolchain mínima fixa;
- [ ] decidir como o `Cargo.lock` entra na política;
- [ ] testar os crates publicados separadamente em workspaces;
- [ ] documentar como aumentos de MSRV se relacionam com SemVer;
- [ ] destacar qualquer aumento nas notas de release;
- [ ] repetir a investigação ao atualizar dependências importantes.

## cargo-msrv e carreira Rust

MSRV parece um detalhe de mantenedor, mas aparece em trabalhos de plataforma, bibliotecas, CLIs e open source. Saber explicar o problema demonstra que você entende Rust como ecossistema distribuído, não apenas como compilador local.

Em uma entrevista, uma resposta madura para “como garantir compatibilidade com uma versão antiga do Rust?” inclui:

1. declarar `rust-version`;
2. definir a matriz de features e targets;
3. descobrir a baseline com `cargo-msrv`;
4. testar diretamente a toolchain mínima na CI;
5. controlar atualizações de dependências;
6. documentar a política de aumento.

Esse repertório é relevante para equipes que mantêm SDKs, crates públicos, ferramentas de infraestrutura e software empacotado por distribuições. Consulte as [vagas Rust](/vagas/), o diretório de [empresas que usam Rust](/empresas/) e o [plano de estudos sênior](/carreira/plano-estudos-senior/) para conectar tooling e compatibilidade à evolução profissional.

## Perguntas frequentes

### O que é MSRV em Rust?

MSRV significa *Minimum Supported Rust Version*: a versão mínima do compilador que o projeto declara suportar para uma configuração documentada de código, dependências, features e targets.

### Para que serve o cargo-msrv?

O `cargo-msrv` automatiza a descoberta e a verificação dessa versão. Ele testa toolchains candidatas e ajuda a conferir se o valor declarado em `rust-version` continua verdadeiro.

### Qual é a diferença entre cargo msrv find e cargo msrv verify?

`cargo msrv find` procura a versão mínima que atende ao teste configurado. `cargo msrv verify` valida a MSRV já declarada pelo projeto. Use a busca para estabelecer ou revisar a baseline e a verificação para impedir regressões.

### Onde declarar a versão mínima do Rust?

Use `rust-version` na seção `[package]` do `Cargo.toml`. Em workspaces compatíveis, o valor pode ser centralizado em `[workspace.package]` e herdado pelos pacotes membros.

### MSRV faz parte do SemVer?

A interpretação varia entre projetos, mas elevar a MSRV pode quebrar consumidores sem alterar a API. Portanto, publique uma política, teste a versão prometida e destaque aumentos nas notas de release.

## Conclusão

O `cargo-msrv` torna a versão mínima do Rust mensurável. Em vez de escrever “suporta Rust antigo” no README, você descobre uma baseline, declara `rust-version`, testa a toolchain na CI e revisa o contrato quando dependências ou features mudam.

O processo recomendado é: **rode `cargo msrv find`, confirme a combinação real de features e targets, declare `rust-version`, teste essa toolchain em toda pull request e use `cargo msrv verify` como auditoria**. Para bibliotecas, trate aumentos como uma mudança relevante para consumidores e comunique-os com a mesma disciplina aplicada à API pública.

Continue a trilha com [cargo-semver-checks](/blog/cargo-semver-checks-rust-api-ci-2026/), [cargo-machete e cargo-udeps](/blog/cargo-machete-cargo-udeps-dependencias-nao-usadas-2026/) e [segurança de supply chain com cargo-deny e SBOM](/blog/rust-seguranca-supply-chain-cargo-deny-sbom-2026/). Juntas, essas ferramentas ajudam a manter não só um build que passa hoje, mas um projeto que continua consumível, auditável e previsível ao longo das releases.