Erro E0463 do Rust: can't find crate (crate não encontrado)

O E0463 quer dizer que o compilador foi procurar um crate inteiro (uma biblioteca) e voltou de mãos vazias. Normalmente o seu código tem uma linha extern crate para um crate que não está no Cargo.toml. Às vezes o crate que falta é o próprio std, o que acontece quando você compila para outro tipo de máquina e ainda não instalou esse target. Os dois casos têm correções rápidas, e você não precisa entender de linkers para aplicá-las. Esta página faz parte do guia de erros do compilador.

A mensagem de erro

error[E0463]: can't find crate for `rand`
 --> src/main.rs:1:1
  |
1 | extern crate rand;
  | ^^^^^^^^^^^^^^^^^^ can't find crate

Em português: “não encontrei o crate rand”. O compilador aponta a linha extern crate rand; e diz que não achou essa biblioteca.

Este é o programa que gera o erro, num projeto novo criado com cargo new, sem nada em [dependencies]:

extern crate rand;

fn main() {
    let roll = rand::random_range(1..=6);
    println!("You rolled {roll}");
}

A segunda forma comum não tem número de linha nenhum, porque nenhuma linha do seu código pede o std. Todo programa precisa dele:

error[E0463]: can't find crate for `std`
  |
  = note: the `aarch64-unknown-linux-gnu` target may not be installed
  = help: consider downloading the target with `rustup target add aarch64-unknown-linux-gnu`

A nota diz que o target aarch64-unknown-linux-gnu talvez não esteja instalado, e a ajuda sugere baixá-lo com rustup target add. Você recebe isso com cargo build --target aarch64-unknown-linux-gnu (Linux em ARM de 64 bits, como num Raspberry Pi) quando só o target da sua própria máquina está instalado. A correção certa depende do nome do crate e da note::

O que você vê	O que costuma ter dado errado	Correção
can't find crate for `rand` numa linha extern crate	o crate não está no Cargo.toml	Correção 1
o mesmo, em código antigo com #[macro_use]	código escrito antes da edição 2018	Correção 2
can't find crate for `std` + target may not be installed	compilando para um target que o rustup não baixou	Correção 3
crate name using dashes are not valid junto com o E0463	um - no nome do crate dentro do código	Correção 4

O que significa

extern crate rand; diz ao compilador: “junte a biblioteca compilada chamada rand a este programa”. O compilador não baixa nada e não procura na internet. Ele só olha as bibliotecas que o Cargo entrega para ele, e o Cargo só entrega os crates listados no Cargo.toml. Sem rand lá, não há biblioteca rand na lista, e aí vem o E0463.

O caso do std é a mesma ideia, um nível abaixo. A biblioteca padrão também é uma biblioteca compilada, e o rustup instala uma cópia por target. A sua toolchain normal só tem a cópia para o seu próprio computador. Peça um build para ARM e o compilador procura uma cópia ARM do std que não está lá.

É como uma receita que diz “use a farinha do armário”. Se ninguém comprou farinha, o cozinheiro não consegue começar, por melhor que seja a receita.

Por que o Rust faz isso

O Rust não tem uma pasta global e compartilhada de bibliotecas instaladas, como o pip install do Python ou um node_modules para o sistema todo. Cada projeto diz exatamente o que usa no Cargo.toml, com as versões, e o Cargo compila esses crates para aquele projeto. É por isso que o mesmo projeto compila do mesmo jeito no seu notebook, na máquina de um colega e no CI. Um crate que não está escrito ali simplesmente não existe para o seu código.

O extern crate é basicamente uma sobra do Rust 2015. Desde a edição 2018, todo crate do Cargo.toml fica disponível automaticamente, então o código moderno só escreve use rand::random_range;. Você ainda encontra extern crate em tutoriais antigos e respostas do Stack Overflow, e é daí que vem a maioria dos E0463. Hoje, sem a dependência, uma linha use dá o E0432 e um caminho no código dá o E0433. Mesma causa, outro código de erro.

Veja Cargo e crates para entender como funcionam as dependências e Ferramentas do Rust para toolchains e targets.

Como corrigir

Correção 1: Adicione o crate com cargo add

Escolha esta quando o crate que falta vem do crates.io, como rand, regex ou serde_json. É o caso mais comum. Rode isto na pasta que tem o Cargo.toml:

cargo add rand

O Cargo adiciona a versão mais nova para você:

[dependencies]
rand = "0.10.3"

Só isso já corrige o E0463. Aproveite e apague a linha extern crate rand;; você não precisa dela na edição 2018 ou mais nova (confira o edition = no Cargo.toml). Esta versão imprime uma verificação em vez do número sorteado, para que a saída seja sempre a mesma:

fn main() {
    let roll = rand::random_range(1..=6);
    println!("O dado deu entre 1 e 6: {}", (1..=6).contains(&roll));
}

Saída:

O dado deu entre 1 e 6: true

▶ Experimente você mesmo

Código antigo também pode chamar funções que mudaram de uma versão para outra. Se o cargo add resolver o E0463 mas depois aparecer o E0425 ou o E0432 para algo como thread_rng, confira a documentação do crate para a versão que você tem. Veja Adicionando uma dependência com cargo add.

Correção 2: Troque as linhas extern crate antigas por use

Escolha esta quando você copiou código anterior a 2018. Ele costuma começar com um bloco assim, e cada linha pode dar E0463:

#[macro_use]
extern crate serde_derive;
extern crate serde_json;

#[derive(Serialize)]
struct Order {
    item: String,
    qty: u32,
}

error[E0463]: can't find crate for `serde_derive`
 --> src/main.rs:2:1
  |
2 | extern crate serde_derive;
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^ can't find crate

error[E0463]: can't find crate for `serde_json`
 --> src/main.rs:3:1
  |
3 | extern crate serde_json;
  | ^^^^^^^^^^^^^^^^^^^^^^^^ can't find crate

São dois E0463, um para cada linha extern crate. Não adicione o serde_derive como um crate separado. Hoje as macros de derive vêm junto com o serde quando você liga a feature derive:

cargo add serde --features derive
cargo add serde_json

Depois apague o bloco extern crate e importe o que você usa com uma linha use normal. O #[macro_use] também não é mais necessário:

use serde::Serialize;

#[derive(Serialize)]
struct Order {
    item: String,
    qty: u32,
}

fn main() {
    let order = Order { item: String::from("maçã"), qty: 3 };
    println!("{}", serde_json::to_string(&order).unwrap());
}

Saída:

{"item":"maçã","qty":3}

▶ Experimente você mesmo

Se uma linha extern crate cita um crate que o seu código nunca usa de verdade, é só apagar a linha. A lição JSON com serde mostra a configuração moderna completa.

Correção 3: Instale o target com rustup target add

Escolha esta quando o erro fala do std (ou do core) e a note: diz que o target talvez não esteja instalado. Copie o nome do target da linha help::

rustup target add aarch64-unknown-linux-gnu
rustup target list --installed    # confira o que você tem agora

Depois compile de novo com o mesmo --target. Um target é o tipo de máquina para a qual você compila, escrito como uma “tripla” (triple), como aarch64-unknown-linux-gnu ou wasm32-unknown-unknown. O rustup baixa o std já compilado para ele, e o E0463 vai embora.

Duas observações. Primeiro, para muitos targets esse não é o último passo: compilar um programa completo para outro sistema operacional costuma precisar também de um linker para aquela plataforma, e isso é outro erro. Segundo, se o projeto tiver um rust-toolchain.toml, rode o comando dentro da pasta do projeto, para o rustup adicionar o target à toolchain que aquele projeto usa de fato. Veja Componentes e targets e a lição de WebAssembly para um target que você provavelmente vai usar.

Correção 4: Escreva hífens como underscores no código

Escolha esta quando o nome do crate tem hífen, como serde-json ou tracing-subscriber. No Cargo.toml e na linha de comando o hífen não tem problema. No código Rust, um - é o sinal de menos, então o nome é sempre escrito com _. Código antigo com hífen dá isto:

error: crate name using dashes are not valid in `extern crate` statements
 --> src/main.rs:1:14
  |
1 | extern crate serde-json;
  |              ^^^^^^^^^^ dash-separated idents are not valid
  |
help: if the original crate name uses dashes you need to use underscores in the code
  |
1 - extern crate serde-json;
1 + extern crate serde_json;
  |

error[E0463]: can't find crate for `serde_json`

O rustc diz que nomes com hífen não valem em extern crate e sugere trocar por underscore. Ele já lê o nome como serde_json, então o E0463 logo abaixo só aparece quando o crate também não está no Cargo.toml. Numa linha use, um hífen dá outra mensagem, expected one of `::`, `;`, or `as`, found `-` . A correção é a mesma em todo lugar: cargo add no crate se precisar e _ no código:

use serde_json::json;

fn main() {
    let order = json!({ "item": "maçã", "qty": 3 });
    println!("{order}");
}

Saída:

{"item":"maçã","qty":3}

▶ Experimente você mesmo

A mesma regra vale para o seu próprio pacote: um projeto chamado shop-app é importado como shop_app a partir do main.rs e dos testes.

Onde você costuma ver esse erro

Rodando rustc main.rs direto. O rustc sozinho não lê o Cargo.toml, então mesmo depois de cargo add rand, rustc --edition 2021 src/main.rs continua dizendo can't find crate for `rand` para uma linha extern crate rand; (e E0432 para uma linha use rand::...). Correção: compile com cargo run ou cargo build, que passam as suas dependências para o compilador.

Um crate listado em [dev-dependencies]. As dev-dependencies (adicionadas com cargo add --dev) só existem para testes, exemplos e benchmarks. Usar uma delas no código normal dá E0463 com extern crate, ou E0433 com um caminho. Correção: mova para [dependencies] com cargo remove --dev serde_json e depois cargo add serde_json.

Placas embarcadas sem sistema operacional. Para um target como thumbv7em-none-eabihf, instalar não basta, porque ele não tem std nenhum. A nota muda para dizer isso:

error[E0463]: can't find crate for `std`
  |
  = note: the `thumbv7em-none-eabihf` target may not support the standard library
  = note: `std` is required by `shop` because it does not declare `#![no_std]`

As notas dizem que esse target talvez não suporte a biblioteca padrão e que o pacote shop precisa do std porque não declara #![no_std]. Correção: escreva o programa como #![no_std], o que também significa ficar sem println! e ter o seu próprio panic handler. O Embedded Rust Book (em inglês) mostra o caminho passo a passo.

Erros relacionados

• E0432: unresolved import (import não resolvido), o que uma linha use dá quando o crate não está no Cargo.toml.
• E0433: failed to resolve (falha ao resolver), o que um caminho como rand::rng() dá quando o crate está faltando.
• E0603: o crate foi encontrado, mas o item que você quer dele é privado.
• crate name using dashes are not valid: este não tem código de erro; escreva _ em vez de - (Correção 4).
• Todos os erros do compilador: a lista completa de páginas de erro.

Teste o que aprendeu

Teste o que aprendeu

1. Um código antigo começa com extern crate regex; e você recebe o E0463. Qual é a melhor correção num projeto da edição 2021?

Rodar cargo add regex e apagar a linha extern crate Trocar para extern crate std::regex; Rodar rustup target add regex

2. cargo build --target wasm32-unknown-unknown diz que não encontra o crate std e que o target talvez não esteja instalado. O que você roda?

cargo add std cargo update rustup target add wasm32-unknown-unknown

3. Seu Cargo.toml tem tracing-subscriber = "0.3". Como você escreve o nome do crate no código Rust?

tracing-subscriber tracing_subscriber TracingSubscriber

Pontuação: 0 / 3

Para saber mais

• E0463 — Rust error codes index (em inglês): a explicação oficial do caso do crate que falta.
• Increasing Functionality with a Crate — The Rust Book (em inglês): como adicionar a sua primeira dependência no Cargo.toml, passo a passo.
• Specifying Dependencies — The Cargo Book (em inglês): versões, features e a diferença entre [dependencies] e [dev-dependencies].
• Path and module changes in Rust 2018 — Edition Guide (em inglês): por que o extern crate não é mais necessário.
• Cross-compilation — The rustup book (em inglês): como instalar targets com rustup target add.