できない.dev

Rust「failed to resolve: use of undeclared crate or module」の原因と直し方

use of undeclared crate or module は、Cargo.toml に依存を足すか mod 宣言を書けば直る。
Rust 1.95 以降は cannot find module or crate と表示される。

公開: 更新:

症状できない · exit 101
cargo build
…
error[E0433]: cannot find module or crate `utils` in this scope
 --> src/main.rs:2:5
  |
2 |     utils::helper();
解決後できた · exit 0
cargo build
Compiling demo v0.1.0 (/tmp/tmp.sWkP2T5inv/demo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.14s

2026-09-13 に rust:1(Python 3.13.5 / Git 2.47.3) で実際に打って取った出力。検証環境の詳細

要約

E0433 は型エラーではなく 名前解決 のエラーである。
コンパイラーは「この名前に対応するクレートもモジュールも、いま見えている範囲に無い」と言っている。

同じ E0433 でも、Rust のバージョンによって 1 行目の文言が違う(utils の部分はコードに書いた名前)。

  • 1.86 より前: error[E0433]: failed to resolve: use of undeclared crate or module `utils`
  • 1.86〜1.94: error[E0433]: failed to resolve: use of unresolved module or unlinked crate `utils`
  • 1.95 以降: error[E0433]: cannot find module or crate `utils` in this scope(下線の注記は use of unresolved module or unlinked crate `utils`)

1.86 の変更は rust-lang/rust の PR #133154(新しいタブで開く)、1.95 の変更は PR #145399(新しいタブで開く) による。
文言が違っても原因と直し方は変わらない。
下の実行例は Rust 1.98.1 での実測なので、1.95 以降の文言になっている。

見えている範囲を決めるのは 2 つだけである。
外部クレートなら Cargo.toml の [dependencies]、自作コードなら mod 宣言によるモジュールツリーへの接続である。
どちらの話なのかを最初に決めれば、直し方は一つに定まる。
綴りが合っているのに出る場合は、ほぼ後者の接続漏れである。

実行例

src/utils.rs を置いただけで mod 宣言が無い状態だと、Rust 1.98.1 のコンパイラーは cannot find module or crate という文言で E0433 を出し、ヘルプに mod utils; の追加まで示してくる。
依存を書かずに serde_json を使うと use の行は E0432、serde_json::from_str の行は E0433 と分かれて報告され、cargo add serde_json のあとは同じコードがビルドを通って JSON の出力まで表示された。

$ cargo build
Compiling demo v0.1.0 (/tmp/tmp.sWkP2T5inv/demo)
error[E0433]: cannot find module or crate `utils` in this scope
 --> src/main.rs:2:5
  |
2 |     utils::helper();
  |     ^^^^^ use of unresolved module or unlinked crate `utils`
  |
help: to make use of source file src/utils.rs, use `mod utils` in this file to declare the module
  |
1 + mod utils;
  |
 
For more information about this error, try `rustc --explain E0433`.
error: could not compile `demo` (bin "demo") due to 1 previous error
$ echo $?
101
$ cargo build
Compiling demo v0.1.0 (/tmp/tmp.sWkP2T5inv/demo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.14s
$ echo $?
0
$ cargo run
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/demo`
helper called
$ cargo build
Compiling demo v0.1.0 (/tmp/tmp.sWkP2T5inv/demo)
error[E0432]: unresolved import `serde_json`
 --> src/main.rs:3:5
  |
3 | use serde_json::Value;
  |     ^^^^^^^^^^ use of unresolved module or unlinked crate `serde_json`
  |
  = help: if you wanted to use a crate named `serde_json`, use `cargo add serde_json` to add it to your `Cargo.toml`
 
error[E0433]: cannot find module or crate `serde_json` in this scope
 --> src/main.rs:7:20
  |
7 |     let v: Value = serde_json::from_str(r#"{"a":1}"#).unwrap();
  |                    ^^^^^^^^^^ use of unresolved module or unlinked crate `serde_json`
  |
  = help: if you wanted to use a crate named `serde_json`, use `cargo add serde_json` to add it to your `Cargo.toml`
 
Some errors have detailed explanations: E0432, E0433.
For more information about an error, try `rustc --explain E0432`.
error: could not compile `demo` (bin "demo") due to 2 previous errors
$ echo $?
101
$ cargo add serde_json
Updating crates.io index
      Adding serde_json v1.0.151 to dependencies
             Features:
             + std
             - alloc
             - arbitrary_precision
             - float_roundtrip
             - indexmap
             - preserve_order
             - raw_value
             - unbounded_depth
    Updating crates.io index
     Locking 11 packages to latest Rust 1.98.1 compatible versions
      Adding itoa v1.0.18
      Adding memchr v2.8.3
      Adding proc-macro2 v1.0.107
      Adding quote v1.0.47
      Adding serde v1.0.229
      Adding serde_core v1.0.229
      Adding serde_derive v1.0.229
      Adding serde_json v1.0.151
      Adding syn v3.0.5
      Adding unicode-ident v1.0.24
      Adding zmij v1.0.23
$ cargo build
Downloading crates ...
  Downloaded itoa v1.0.18
  Downloaded zmij v1.0.23
  Downloaded serde_json v1.0.151
  Downloaded serde_core v1.0.229
  Downloaded memchr v2.8.3
   Compiling zmij v1.0.23
   Compiling serde_core v1.0.229
   Compiling serde_json v1.0.151
   Compiling memchr v2.8.3
   Compiling itoa v1.0.18
   Compiling demo v0.1.0 (/tmp/tmp.sWkP2T5inv/demo)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.77s
$ echo $?
0
$ cargo run
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/demo`
helper called
{"a":1}

— 2026-09-13 時点の出力

検証環境Python 3.13.5 / Git 2.47.3 / 2026-09-13 検証
検証日
実行環境
rust:1 Debian GNU/Linux 13 (trixie)
バージョン
  • Python 3.13.5
  • Git 2.47.3

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 外部クレートなら依存を追加する

cargo add serde_json

Cargo.toml には次の行が入る。
手で書いてもよいが、cargo add はバージョンを調べて入れてくれるぶん確実である。

[dependencies]
serde_json = "1"

追加したら cargo build をやり直す。
エディターの表示が更新されない場合は rust-analyzer の再読み込みが必要なことがあるが、コンパイル自体はこれで通る。

2. 自作モジュールは mod で接続する

src/utils.rs を作っただけでは、まだどこからも見えていない。
親(src/main.rs か src/lib.rs)に宣言を書く。

// src/main.rs
mod utils;              // これが無いと utils::helper は E0433 になる
 
fn main() {
    utils::helper();
}

ディレクトリで区切る場合は、src/utils/mod.rs(または src/utils.rs)が子モジュールをまとめる役になり、その中でさらに mod を書く。

// src/utils/mod.rs
pub mod text;
pub mod path;

3. ハイフンとアンダースコアの読み替え

Cargo.toml に書くパッケージ名と、コードで使う識別子は表記が違う。

[dependencies]
serde-json = "1"     # ハイフンでも受け付けられる
use serde_json::Value;   // コード側は必ずアンダースコア

エラーメッセージのクレート名がハイフン付きになっていたら、この読み替え漏れを疑う。

4. ワークスペースの別クレートを参照する

同一ワークスペースでも、依存の宣言は必要である。

[dependencies]
my-core = { path = "../my-core" }

5. 似たエラーと取り違えない

use of undeclared type(型名が見つからない)は同じ E0433 でも別の問題で、use の書き忘れなどが原因である。
E0433 のうちこの記事が扱うのは、パスの入口となるクレート・モジュール自体が見つからない状態なので、パスの 1 つ目の要素に注目して切り分ける。

また、依存を書き忘れたクレートを use 文で読み込んだ行は、E0433 ではなく E0432(unresolved import)として報告される。
その場合も注記が use of unresolved module or unlinked crate なら、原因と直し方は E0433 と同じである。

よくある原因

  1. 依存を書かずに使っている: サンプルコードを貼り付けたときの定番で、cargo add を忘れている。
  2. ファイルは作ったが mod を書いていない: Rust はディレクトリを走査してモジュールを自動登録しない。
    親から mod で明示的に接続する必要がある。
  3. クレート名のハイフンをそのまま書いている: パッケージ名 serde-json は、コード上の識別子としては serde_json になる。
  4. ワークスペースの別クレートを参照している: 同じリポジトリにあっても、依存として宣言していなければ外部のクレートと同じ扱いである。

この手順で直った?