Cargoとは？使い方とコマンド一覧｜Rustのbuild・testの実行結果つき

Cargo は、Cargo.toml に書いた依存ライブラリ（クレート）を crates.io から取り寄せ、コンパイラ rustc を正しい順番と引数で呼び、できあがった実行ファイルを target/ に置くまでを引き受けます。

flowchart TD
    T[Cargo.toml<br>欲しいクレートと版の範囲] --> R[依存の解決]
    R --> L[Cargo.lock<br>実際に使う版を固定]
    L --> D[crates.io から取得<br>~/.cargo/registry]
    D --> C[rustc を順番に呼ぶ]
    C --> O[target/debug または<br>target/release に出力]

よく調べられることの答えを先にまとめます。

確認環境：Ubuntu 24.04.5 LTS（x86_64・2 CPU・メモリ 7GB）に rustup で入っていた stable ツールチェーン（cargo 1.97.0・rustc 1.97.0、2026年6〜7月のリリース）を使い、CARGO_HOME を作業用のフォルダーに向けて、記事中のコマンドをすべて実行しました。クレートは crates.io から取得できたため、rand 0.10.3・serde 1.0.229・serde_json 1.0.154・ripgrep 15.2.0 を実際に取り寄せています。apt の cargo は Ubuntu 24.04 では 1.75.0 で、apt-cache policy で版だけ確かめました（入れていません）。速度は他の処理と同じマシンで測ったため、同じ条件でも 2 倍ほど変動することがあり、本文では 7 回測った中央値を書いています。Windows・Mac のインストール手順は rust-lang.org の公式ページ、Cargo.lock の扱いは The Cargo Book で確かめました（確認日 2026年10月29日）。

Cargoとは（Rustのビルドツール・パッケージマネージャー）

この節では、Cargo が何をする道具で、rustc と何が違うのかが分かります。

Cargo は、Rust のプロジェクトを「作る・組み立てる・試す・配る」ための公式ツールです。 Rust のコンパイラは rustc ですが、ふだん手で rustc を打つことはほとんどなく、Cargo が代わりに呼びます。読み方は「カーゴ」、英語で「積み荷」の意味で、Rust ではライブラリの単位を crate（クレート。木箱）と呼ぶのと対になっています。

Cargo が引き受ける仕事は、次の5つにまとまります。

rustc を直接使うとどうなるかも確かめました。1ファイルなら rustc one.rs で実行ファイル one（4,359,648 バイト）ができます。ただし、ファイルが増える・ライブラリを使う・テストを書く、となった途端に、rustc の引数は次のように長くなります。cargo build -v で Cargo が実際に rustc をどう呼んでいるかを見た一部です。

$ cargo build -v
     Running `rustc --crate-name bench --edition=2024 src/main.rs --error-format=json
       --json=diagnostic-rendered-ansi,artifacts,future-incompat --crate-type bin
       --emit=dep-info,link -C embed-bitcode=no -C debuginfo=2
       --check-cfg 'cfg(docsrs,test)' --check-cfg 'cfg(feature, values())'
       -C metadata=28685efda35f8120 -C extra-filename=-feb9e75b9aa339fa
       --out-dir /dev/shm/t113/bench/target/debug/deps ...`

この引数を毎回手で組み立てる代わりに cargo build と打つ、というのが Cargo の役割です。Rust 言語そのものの特徴や所有権は、Rust の入門記事「Rust言語とは？特徴・できること・入門｜所有権エラーと速度を実測」で扱い、この記事は Cargo の使い方に絞ります。

Cargoのインストールとバージョン確認（rustup・apt）

この節では、Cargo をどう入れ、入っているかをどう確かめるかが分かります。

Cargo は単独では配られておらず、Rust と一緒に入れます。 公式の手段は rustup で、rust-lang.org のインストールページには次のように書かれています。

$ cargo --version
cargo 1.97.0 (c980f4866 2026-06-30)
$ rustc --version
rustc 1.97.0 (2d8144b78 2026-07-07)
$ cargo version --verbose
cargo 1.97.0 (c980f4866 2026-06-30)
release: 1.97.0
host: x86_64-unknown-linux-gnu
os: Ubuntu 24.4.0 (noble) [64-bit]

Ubuntu の apt にも cargo・rustc パッケージがあります。Ubuntu 24.04 で apt-cache policy cargo を見ると候補は 1.75.0 で、rustup の stable（1.97.0）より 22 版前です。学習や試用には動きますが、新しいクレートは rust-version（後述）で 1.75 を断ることがあるため、公式の rustup を使うのが確実です。rustup なら rustup update で Cargo も一緒に更新されます。

cargo newでプロジェクトを作る（生成されるファイル）

この節では、cargo new が何を作るのか、--lib と cargo init との違いが分かります。

cargo new 名前 は、フォルダー・Cargo.toml・src/main.rs・.gitignore を作り、git リポジトリも初期化します。 手元で実行した結果です。

$ cargo new hello
    Creating binary (application) `hello` package
note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

$ find hello -type f -not -path '*/.git/*'
hello/.gitignore
hello/Cargo.toml
hello/src/main.rs

$ cat hello/Cargo.toml
[package]
name = "hello"
version = "0.1.0"
edition = "2024"

[dependencies]

$ cat hello/src/main.rs
fn main() {
    println!("Hello, world!");
}

$ cat hello/.gitignore
/target

--lib で作った src/lib.rs の雛形には、最初からテストが1つ入っています。

pub fn add(left: u64, right: u64) -> u64 {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

パッケージ名には決まりがあり、数字で始まる名前と、標準ライブラリとぶつかる名前は断られます。原文です。

$ cargo new 1st-app
error: invalid character `1` in package name: `1st-app`, the name cannot start with a digit
note: the directory name is used as the package name
help: to override the package name, pass `--name <pkgname>`

$ cargo new test
error: invalid package name `test`: it conflicts with Rust's built-in test library

どちらも --name で別のパッケージ名を付ければ、フォルダー名はそのままで作れます。

cargo build・run・checkの使い方（出力とtarget/の中身）

この節では、ビルドの3つのコマンドの違いと、target/ に何ができるか、2回目のビルドが速い理由が分かります。

cargo build はコンパイルだけ、cargo run はコンパイルして実行、cargo check は実行ファイルを作らずに誤りだけ調べます。 Hello World で実行した結果です。

$ cargo build
   Compiling hello v0.1.0 (/dev/shm/t113/hello)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.20s

$ ls target/debug
build  deps  examples  hello  hello.d  incremental
$ ls -l target/debug/hello
-rwxr-xr-x 2 root root 4367432 ... target/debug/hello

$ cargo build            # 何も変えずにもう一度
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.01s

$ cargo run
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/hello`
Hello, world!

$ cargo check
    Checking hello v0.1.0 (/dev/shm/t113/hello)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.03s

$ cargo build --release
   Compiling hello v0.1.0 (/dev/shm/t113/hello)
    Finished `release` profile [optimized] target(s) in 0.23s
$ ls -l target/release/hello
-rwxr-xr-x 2 root root 445080 ... target/release/hello

$ cargo clean
     Removed 44 files, 9.3MiB total

2回目が 0.01 秒で終わる理由と、check が速い理由

Cargo は、ソースと依存のハッシュを target/ に記録し、変わっていなければ rustc を呼びません（上の「何も変えずにもう一度」が 0.01 秒）。1行だけ直したときは incremental フォルダーの差分コンパイルが働きます。依存クレートを3つ（rand・serde・serde_json、間接依存を含めて 19 個）持つプロジェクトで、最初から・1行直した後・何も変えない、の3通りを測りました。

注：cargo build の直後に初めて cargo check を打つと 2.6 秒かかりました。check は依存クレートについても「メタデータだけ」の成果物を別に作るため、build の成果物をそのまま使い回せないからです。2回目以降の check は 0.3 秒以下になります。最初のビルドは、他の処理が同じマシンで動いていた時間帯には 21 秒かかったこともあり、2 CPU の環境では「依存の初回コンパイルが一番長い」と見ておくと見積もりがずれません。

Cargo.tomlとCargo.lockの違いと書き方

この節では、2つのファイルの役割の違い、Cargo.toml の主な項目、Cargo.lock をコミットするかの答えが分かります。

Cargo.toml は人が書く「欲しいクレートと版の範囲」、Cargo.lock は Cargo が書く「実際に使った正確な版」です。 The Cargo Book は、Cargo.lock は手で編集するものではない、迷ったら Cargo.lock をバージョン管理に入れる、と書いています。

rand・serde・serde_json を足したあとの Cargo.toml と、Cargo.lock の先頭です。Cargo.toml に書いたのは3行ですが、Cargo.lock には間接依存を含む 20 パッケージ（自分を含む）が 175 行で記録されました。

# Cargo.toml（cargo add で書き足された状態）
[package]
name = "hello"
version = "0.1.0"
edition = "2024"

[dependencies]
rand = "0.10.3"
serde = { version = "1.0.229", features = ["derive"] }
serde_json = "1.0.154"

# Cargo.lock（先頭の一部）
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4

[[package]]
name = "cfg-if"
version = "1.0.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"

[[package]]
name = "chacha20"
version = "0.10.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06"
dependencies = [
 "cfg-if",
 "cpufeatures",
 "rand_core",
]

Cargo.toml の主な項目

版の指定の読み方

"1.0.229" のように書いた版は、先頭の ^ が省かれた形で、「互換性のある範囲で、これ以上」を意味します。1.0.229 なら 2.0.0 未満、0.10.3 なら 0.11.0 未満です（0.x 系は 2 桁目が変わると非互換とみなします）。範囲の中でどの版を実際に使ったかを記録するのが Cargo.lock です。

Cargo.lock の先頭の version = 4 はロックファイルの形式の版で、使う Cargo が理解できる版でなければなりません。手元で 99 に書き換えてみると、次のように止まりました。チームで Cargo の版が大きく違うときに出る文言です。

error: failed to parse lock file at: /dev/shm/t113/hello/Cargo.lock

Caused by:
  lock file version `99` was found, but this version of Cargo does not understand this lock file, perhaps Cargo needs to be updated?

TOML という書式そのものの読み方は、関連記事「CSV・JSON・XML・YAML・TOMLの違いと使い分け｜同じデータで比較」で扱っています。

cargo addで依存（クレート）を追加する（tree・update・remove）

この節では、クレートを足す・調べる・上げる・外す一連の操作と、足したあとに起きる典型的なコンパイルエラーが分かります。

cargo add 名前 は、crates.io から最新の版を調べて Cargo.toml に1行書き足し、Cargo.lock を更新します。 ダウンロードとコンパイルは次の cargo build のときに行われます。

$ cargo add rand
    Updating crates.io index
      Adding rand v0.10.3 to dependencies
             Features:
             + alloc
             + std
             + std_rng
             + sys_rng
             + thread_rng
             - chacha
             - log
             - serde
             - simd_support
             - unbiased
    Updating crates.io index
     Locking 8 packages to latest Rust 1.97.0 compatible versions
      Adding cfg-if v1.0.5
      Adding chacha20 v0.10.2
      ...
      Adding rand v0.10.3
      Adding rand_core v0.10.1

$ cargo add serde --features derive      # 機能を指定して追加
$ cargo add --dev assert_cmd             # テスト専用（dev-dependencies）
$ cargo remove --dev assert_cmd          # 外す
    Removing assert_cmd from dev-dependencies

+ が付いた行は既定で有効な機能（features）、- は無効な機能です。「Locking 8 packages」は、rand 1つを足すために間接依存を含めて 8 パッケージの版を固定した、という意味です。

足したクレートを使う：build で取得とコンパイル

rand でサイコロを振り、serde_json で JSON にする main.rs を書いて cargo build しました。最初のビルドでダウンロードと依存のコンパイルが走ります。

$ cargo build
 Downloading crates ...
  Downloaded itoa v1.0.18
  Downloaded getrandom v0.4.3
  ...（18 個）
   Compiling proc-macro2 v1.0.107
   Compiling unicode-ident v1.0.27
   Compiling quote v1.0.47
   Compiling libc v0.2.191
   Compiling serde_core v1.0.229
   ...
   Compiling rand v0.10.3
   Compiling hello v0.1.0 (/dev/shm/t113/hello)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 9.70s

$ cargo run
{"sides":6,"rolls":[6,4,3,4,4]}
Dice { sides: 6, rolls: [6, 4, 3, 4, 4] }

ダウンロードしたクレートは $CARGO_HOME/registry（通常は ~/.cargo/registry）に置かれ、別のプロジェクトでも使い回されます。手元では rand・serde・serde_json・ripgrep を取ったあとで 53MB でした。

tree・update・info・search

$ cargo tree --depth 1
hello v0.1.0 (/dev/shm/t113/hello)
├── rand v0.10.3
├── serde v1.0.229
└── serde_json v1.0.154

$ cargo tree                     # 間接依存まで
hello v0.1.0 (/dev/shm/t113/hello)
├── rand v0.10.3
│   ├── chacha20 v0.10.2
│   │   ├── cfg-if v1.0.5
│   │   ├── cpufeatures v0.3.1
│   │   └── rand_core v0.10.1
│   ├── getrandom v0.4.3
│   ...
├── serde v1.0.229
│   ├── serde_core v1.0.229
│   └── serde_derive v1.0.229 (proc-macro)
│       ├── proc-macro2 v1.0.107
│       ...
└── serde_json v1.0.154
    ├── itoa v1.0.18
    ├── memchr v2.8.3
    ├── serde_core v1.0.229
    └── zmij v1.0.23

$ cargo update --dry-run         # 上げられるものがあるか見るだけ
    Updating crates.io index
     Locking 0 packages to latest Rust 1.97.0 compatible versions
warning: not updating lockfile due to dry run

$ cargo info serde_json          # 公開情報（版・ライセンス・features）
serde_json #json #serde #serialization
A JSON serialization file format
version: 1.0.154
license: MIT OR Apache-2.0
rust-version: 1.71
features:
 +default             = [std]
  preserve_order      = [indexmap, alloc, dep:foldhash]
  ...

$ cargo search toml --limit 3
toml = "1.1.8+spec-1.1.0"           # A native Rust encoder and decoder of TOML-formatted files...
toml-span = "0.7.2"                 # Toml parser and deserializer that preserves span information
toml_edit = "0.25.17+spec-1.1.0"    # Yet another format-preserving TOML parser.

足したあとによく起きる：解説と版が違う

rand の解説の多くは 0.8 系で書かれていて、use rand::Rng; と gen_range を使います。2026年10月29日時点の最新 0.10.3 で同じ書き方をすると、次のエラーになりました。

error[E0599]: no method named `random_range` found for struct `ThreadRng` in the current scope
  --> src/main.rs:12:45
   |
12 |     let rolls: Vec<u8> = (0..3).map(|_| rng.random_range(1..=6)).collect();
   |                                             ^^^^^^^^^^^^
   |
   = help: items from traits can only be used if the trait is in scope
help: trait `RngExt` which provides `random_range` is implemented but not in scope; perhaps you want to import it
   |
 1 + use rand::RngExt;

直し方は、エラーの help: の行をそのまま実行することです。 rustc の提案（use rand::RngExt;）に従ったら通りました。解説どおりに書いて通らないときは、cargo info 名前 か cargo tree で自分の版を確かめ、その版の docs.rs を読みます。どうしても解説と同じ版で試したいなら cargo add rand@0.8 のように版を指定して足せます。

cargo test・doc・fmt・clippyの使い方（テスト・文書・整形・Lint）

この節では、Cargo に組み込まれた品質まわりの4コマンドの出力と、失敗したときの読み方が分かります。

cargo test は、単体テスト・結合テスト・ドキュメントテストの3種類を一度に実行します。 src/lib.rs に関数2つと #[test] 3つ、tests/public_api.rs に結合テスト1つ、関数のコメントにコード例1つを書いて実行した結果です。

/// 2つの数を足します。
///
/// ```
/// assert_eq!(mylib::add(2, 3), 5);
/// ```
pub fn add(left: u64, right: u64) -> u64 {
    left + right
}

/// 税込価格を返します（10%・端数切り捨て）。
pub fn with_tax(price: u64) -> u64 {
    price * 110 / 100
}

$ cargo test
   Compiling mylib v0.1.0 (/dev/shm/t113/mylib)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.19s
     Running unittests src/lib.rs (target/debug/deps/mylib-d8a2a1be2e8416cb)

running 3 tests
test tests::add_works ... ok
test tests::tax_of_1000 ... ok
test tests::tax_rounds_down ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running tests/public_api.rs (target/debug/deps/public_api-1b04c7d482b6f0c5)

running 1 test
test add_via_public_api ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests mylib

running 1 test
test src/lib.rs - add (line 5) ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

わざと期待値を間違えた（101 円の税込を 112 と書いた）ときの出力です。left が実際の値、right が期待した値で、行番号（src/lib.rs:33:9）が付きます。

$ cargo test tax_rounds          # 名前の一部で絞り込み
running 1 test
test tests::tax_rounds_down ... FAILED

failures:

---- tests::tax_rounds_down stdout ----

thread 'tests::tax_rounds_down' (10758) panicked at src/lib.rs:33:9:
assertion `left == right` failed
  left: 111
 right: 112
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

failures:
    tests::tax_rounds_down

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 2 filtered out; finished in 0.00s

error: test failed, to rerun pass `--lib`

cargo doc：コメントから HTML の文書を作る

$ cargo doc
 Documenting mylib v0.1.0 (/dev/shm/t113/mylib)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.35s
   Generated /dev/shm/t113/mylib/target/doc/mylib/index.html

$ ls target/doc/mylib
all.html  fn.add.html  fn.with_tax.html  index.html  sidebar-items.js

/// で書いたコメントが関数ごとのページ（fn.add.html など）になり、cargo doc --open でブラウザが開きます。docs.rs に載っているクレートの文書は、この仕組みで自動生成されたものです。

cargo fmt：整形。--check は CI 向け

崩れた書き方の関数を置いて cargo fmt --check を実行すると、差分を表示して終了コード 1 で終わりました。cargo fmt は実際に書き換えます。

$ cargo fmt --check
Diff in /dev/shm/t113/mylib/src/messy.rs:1:
-pub fn   messy( a:u64,b:u64 )->u64{
-    a+b }
+pub fn messy(a: u64, b: u64) -> u64 {
+    a + b
+}
$ echo $?
1
$ cargo fmt                  # 書き換える

cargo clippy：コンパイルは通るが直したほうがよい書き方を指摘する

C 言語風に書いた「偶数を数える関数」に clippy をかけた結果です。コンパイルは通りますが、5 件の警告が出ました。

pub fn count_even(v: &Vec<u64>) -> usize {
    let mut n = 0;
    for i in 0..v.len() {
        if v[i] % 2 == 0 {
            n += 1;
        }
    }
    return n;
}

$ cargo clippy
warning: unneeded `return` statement
  --> src/lib.rs:45:5
   |
45 |     return n;
   |     ^^^^^^^^
   = note: `#[warn(clippy::needless_return)]` on by default

warning: writing `&Vec` instead of `&[_]` involves a new object where a slice will do
  --> src/lib.rs:38:22
   |
38 | pub fn count_even(v: &Vec<u64>) -> usize {
   |                      ^^^^^^^^^
help: change this to
38 + pub fn count_even(v: &[u64]) -> usize {

warning: the loop variable `i` is only used to index `v`
  --> src/lib.rs:40:14
   = note: `#[warn(clippy::needless_range_loop)]` on by default

warning: manual implementation of `.is_multiple_of()`
  --> src/lib.rs:41:12
   |
41 |         if v[i] % 2 == 0 {
   |            ^^^^^^^^^^^^^ help: replace with: `v[i].is_multiple_of(2)`

warning: `mylib` (lib) generated 5 warnings (run `cargo clippy --fix --lib -p mylib -- ` to apply 2 suggestions)

cargo clippy --fix で機械的に直せる分は自動で直ります。CI では cargo clippy -- -D warnings と書くと警告をエラー扱いにできます。

debugとreleaseの違い（速度・サイズの実測とプロファイル）

この節では、--release を付けると何がどれだけ変わるか、サイズをさらに小さくする設定の効き方が、実測で分かります。

dev プロファイル（既定）は最適化なし・デバッグ情報あり、release プロファイルは最適化あり・デバッグ情報なしです。 3,000 万以下の素数の数え上げ（篩）と、300 万回の文字列生成を行うプログラムで測りました。表の時間は 7 回の中央値です。

プロファイルは Cargo.toml に書きます。名前を付けた独自のプロファイルも作れ、cargo build --profile 名前 で使います。上の表はこの設定で測りました。

[profile.release-small]      # cargo build --profile release-small
inherits = "release"
strip = true                 # シンボルを除く
lto = true                   # クレートをまたいだ最適化
codegen-units = 1            # 並列を減らして最適化を優先
opt-level = "z"              # サイズ優先（速度優先なら 3）
panic = "abort"              # panic 時の巻き戻しコードを省く

[profile.dev-fast]           # 開発中に少しだけ速くしたいとき
inherits = "dev"
opt-level = 1

計測は他の処理も動いているマシンで行ったため、同じビルドでも 1.17〜4.36 秒（dev）のばらつきがありました。中央値で比べていますが、自分の環境で測り直すのが確実です。

ワークスペースとfeaturesの使い方（複数クレート・機能の切り替え）

この節では、複数のパッケージを1つのリポジトリで管理する形と、機能を Cargo.toml で切り替える仕組みが、動かした結果で分かります。

ワークスペースは、複数のパッケージが target/ と Cargo.lock を共有する仕組みです。 ライブラリ pricing と、それを使う実行ファイル cli の2つで作りました。

# shop/Cargo.toml（ワークスペースの親。[package] は無い）
[workspace]
resolver = "3"
members = ["pricing", "cli"]

[workspace.package]          # メンバーで共有する値
version = "0.2.0"
edition = "2024"

[workspace.dependencies]     # メンバーで共有する依存の版
serde = { version = "1", features = ["derive"] }

# shop/cli/Cargo.toml
[package]
name = "cli"
version.workspace = true     # 親の値を使う
edition.workspace = true

[dependencies]
pricing = { path = "../pricing" }

$ cargo build                      # 親フォルダーで。メンバー全部をビルド
   Compiling pricing v0.2.0 (/dev/shm/t113/shop/pricing)
   Compiling cli v0.2.0 (/dev/shm/t113/shop/cli)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.71s
$ ls target/debug
build  cli  cli.d  deps  examples  incremental  libpricing.d  libpricing.rlib
$ ls pricing cli                   # メンバーには target/ ができない
pricing: Cargo.toml  src
cli:     Cargo.toml  src

$ cargo run -p cli -- 2500         # -p でメンバーを選ぶ。-- の後ろがプログラムの引数
features: tax
税込: 2750

$ cargo run -p pricing
error: a bin target must be available for `cargo run`

Cargo.lock も親に1つだけできます。cargo test --workspace で全メンバーのテストが回り、-p 名前 で1つに絞れます。

features：コンパイル時に機能を出し入れする

features は、「この機能を使う人だけコンパイルに含める」ための仕組みです。serde の derive、tokio の full のように、クレートを足すときに指定する features = [...] がこれです。自分のライブラリで定義した例です。

# shop/pricing/Cargo.toml
[features]
default = ["tax"]            # 何も指定しないとき有効
tax = []
discount = []

[dependencies]
serde = { workspace = true, optional = true }   # optional は "serde" という feature になる

#[cfg(feature = "tax")]                 // tax が有効なときだけこの関数が存在する
pub fn with_tax(price: u64) -> u64 {
    price * 110 / 100
}

#[cfg(feature = "discount")]
pub fn discounted(price: u64) -> u64 {
    price * 90 / 100
}

使う側（cli）で default-features = false にして with_tax を呼ぶと、関数そのものが無くなるため次のエラーになります。rustc が「tax feature の後ろに隠れている」と教えてくれる点が助けになります。

error[E0425]: cannot find function `with_tax` in crate `pricing`
 --> cli/src/main.rs:4:33
  |
4 |     println!("税込: {}", pricing::with_tax(price));
  |                                   ^^^^^^^^ not found in `pricing`
  |
note: found an item that was configured out
 --> pricing/src/lib.rs:3:8
  |
2 | #[cfg(feature = "tax")]
  |       --------------- the item is gated behind the `tax` feature
3 | pub fn with_tax(price: u64) -> u64 {
  |        ^^^^^^^^

# 直し方：使う側で必要な feature を指定する
pricing = { path = "../pricing", default-features = false, features = ["tax", "discount"] }

$ cargo tree -e features -p cli      # どの feature が有効かを見る
cli v0.2.0 (/dev/shm/t113/shop/cli)
├── pricing feature "discount"
│   └── pricing v0.2.0 (/dev/shm/t113/shop/pricing)
└── pricing feature "tax"
    └── pricing v0.2.0 (/dev/shm/t113/shop/pricing)

$ cargo build -p pricing --features serde   # optional な依存が初めてコンパイルされる
   Compiling serde_derive v1.0.229
   Compiling pricing v0.2.0 (/dev/shm/t113/shop/pricing)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 6.98s

cargo installでCLIツールを入れる（ripgrepの実物）

この節では、Rust 製のコマンドを crates.io からビルドして入れる手順と、どこに入るか、更新と削除の方法が分かります。

cargo install 名前 は、crates.io からソースを取り、release でビルドして $CARGO_HOME/bin（通常 ~/.cargo/bin）に実行ファイルを置きます。 ripgrep（rg コマンド）を入れた結果です。2 CPU で 1 分 0 秒かかりました。

$ cargo install ripgrep --locked
    Updating crates.io index
 Downloading crates ...
  Installing ripgrep v15.2.0
    Finished `release` profile [optimized + debuginfo] target(s) in 1m 00s
  Installing /srv/s4/r17/t113/cargo-home/bin/rg
   Installed package `ripgrep v15.2.0` (executable `rg`)
warning: be sure to add `/srv/s4/r17/t113/cargo-home/bin` to your PATH to be able to run the installed binaries

$ rg --version
ripgrep 15.2.0

$ cargo install --list
ripgrep v15.2.0:
    rg

$ cargo uninstall ripgrep
    Removing /srv/s4/r17/t113/cargo-home/bin/rg

手元のプロジェクトを cargo install --path . で入れたときは、release ビルドに 14.6 秒かかり、cargo-home/bin/hello ができました。ビルドの作業用フォルダーは、CARGO_TARGET_DIR を指定しなければ一時フォルダーに作られ、終わると消えます。

cargoコマンド一覧（早見表）

この節では、組み込みのサブコマンドを「何をしたいか」で引けます。

cargo --list で出た 48 個（別名・削除済みの項目を含む）のうち、使う頻度の高いものを並べました。b・c・r・t・d・rm は組み込みの別名です。

自分の別名は .cargo/config.toml に書けます。プロジェクト直下に置けばそのプロジェクトだけ、~/.cargo/config.toml なら全部に効きます。手元で br = "build --release" を定義し、cargo br で release ビルドができました。

# .cargo/config.toml
[alias]
t = "test"
br = "build --release"

[build]
# target-dir = "/path/to/shared/target"   # target/ の場所を変える

npm・pip・Maven・Goとの対応表（他の言語から来た人向け）

この節では、すでに使っているパッケージマネージャーの知識を Cargo に読み替えられます。

大きな違いは、Cargo は依存をプロジェクトの中（node_modules のような場所）に置かず、~/.cargo/registry に1回だけ置いて全プロジェクトで共有する点と、言語のビルドツールと依存管理が最初から1つである点です。それぞれの道具は、関連記事「npm コマンド 一覧｜package.json 書き方と実行結果・npm 12対応」、関連記事「pipコマンド一覧｜installのバージョン指定とrequirements.txt」、関連記事「mvnコマンド一覧とpom.xmlとは｜基本5つの実行ログとオプション早見表」、関連記事「go mod init・tidyの使い方｜go.modとgo.sumとは」で扱っています。

Cargoでよくあるエラー・つまずき（原文つき）

この節では、手元で実際に起こした 13 種のエラーの原文と、原因・直し方が分かります。

いくつかの原文です。

$ cargo build                      # プロジェクトの外で
error: could not find `Cargo.toml` in `/dev/shm/t113` or any parent directory

$ cargo build                      # use regex::Regex; と書いたが足していない
error[E0432]: unresolved import `regex`
 --> src/main.rs:1:5
  |
1 | use regex::Regex;
  |     ^^^^^ use of unresolved module or unlinked crate `regex`
  |
  = help: if you wanted to use a crate named `regex`, use `cargo add regex` to add it to your `Cargo.toml`

$ cargo build                      # edition = "2025" と書いた
error: failed to parse manifest at `/dev/shm/t113/hello/Cargo.toml`
Caused by:
  failed to parse the `edition` key
Caused by:
  this version of Cargo is older than the `2025` edition, and only supports `2015`, `2018`, `2021`, and `2024` editions.

$ cargo build                      # serde_json = "9.0" と書いた
error: failed to select a version for the requirement `serde_json = "^9.0"`
candidate versions found which didn't match: 1.0.154, 1.0.153, 1.0.152, ...
location searched: crates.io index
required by package `hello v0.1.0 (/dev/shm/t113/hello)`

$ cargo build --offline            # regex を足した直後に
error: no matching package named `regex` found
location searched: crates.io index
note: offline mode (via `--offline`) can sometimes cause surprising resolution failures

$ cargo run                        # src/bin/tool.rs を足したあと
error: `cargo run` could not determine which binary to run. Use the `--bin` option to specify a binary, or the `default-run` manifest key.
available binaries: hello, tool

$ cargo build                      # rust-version = "1.99" と書いた
error: rustc 1.97.0 is not supported by the following package:
  hello@0.1.0 requires rustc 1.99

リンカーが無い（linker `cc` not found）

この環境には gcc が入っていたため再現できませんでしたが、新しい Linux に rustup だけ入れると、error: linker `cc` not found で止まることがあります。Rust は実行ファイルを作る最後の段階で C のリンカーを使うためで、Ubuntu・Debian なら build-essential、Windows なら公式ページが案内する Visual Studio C++ Build Tools を入れます。

Cargo の設定で速度が変わるときの確認リスト

• 1速さを測るのに --release を付けたかdev と release で 7.8 倍の差があった
• 2Cargo.lock をコミットしたかCI と手元で同じ版になる。迷ったら入れる（公式）
• 3target/ を .gitignore に入れたかcargo new が作る。19 クレートで 163MB になった
• 4CI で cargo fmt --check と cargo clippy -- -D warnings を回しているか整形の差分で終了コード 1 になる
• 5ツールの導入に --locked を付けたか付けないと依存は最新が選ばれる
• 6解説と自分のクレートの版が同じかrand は 0.8 と 0.10 で書き方が変わった

Cargoを覚える順番

どこから手を付けると迷わないか、順番にしました。

1. 1cargo new → cargo runまず動かす。Cargo.toml は触らない
2. 2cargo check をエディタと一緒にrust-analyzer は裏で check を回している。エラーの help を読む癖をつける
3. 3cargo add と cargo treeクレートを足し、Cargo.toml と Cargo.lock の両方が変わるのを見る
4. 4cargo test・fmt・clippyコミット前の3点セット。CI にも同じものを置く
5. 5--release とプロファイル配る・測るときだけ。strip・lto の効き方は上の表
6. 6ワークスペース・features・installパッケージが2つ以上になってから

よくある質問

Q. cargo と rustc は何が違いますか？ A. rustc はコンパイラ本体、cargo はそれを呼ぶビルドツールです。1ファイルなら rustc main.rs でも動きますが、依存ライブラリ・テスト・複数ファイルがある場合は cargo が rustc の引数を組み立てます（cargo build -v で見られます）。

Q. cargo build と cargo run はどちらを使えばよいですか？ A. 開発中は cargo run だけで進められます。コンパイルして実行まで一度に行い、変更が無ければコンパイルは飛ばされます（手元で 0.01 秒）。実行ファイルだけ欲しいときや、引数なしで実行したくないときに cargo build を使います。

Q. cargo check は何のためにありますか？ A. 実行ファイルを作らず、型検査までで止めるためです。コード生成を省く分だけ速く、エディタの補完や赤線（rust-analyzer）はこれを裏で使っています。手元の最初のビルドでは check 7.8 秒、build 9.7 秒でした。

Q. Cargo.lock は Git にコミットすべきですか？ A. The Cargo Book は「迷ったら入れる」としています。CI と手元、チームの全員で同じ版が使われ、ビルドが突然壊れたときに「コードの変更か、依存の変更か」を切り分けられます。

Q. Cargo.toml に書いた版と、実際に使われる版が違うのはなぜですか？ A. "1.0.229" は「1.0.229 以上 2.0 未満」という範囲の指定だからです。範囲の中で実際に選ばれた版は Cargo.lock に書かれます。"=1.0.229" と書けば固定できますが、通常は範囲のままにして Cargo.lock に任せます。

Q. target/ フォルダーが大きいのですが、消してよいですか？ A. cargo clean で消せます。中身はビルドの成果物とキャッシュで、次のビルドで作り直されます（手元では 19 クレートで 163MB、消したあとの最初のビルドは 9.7 秒）。複数のプロジェクトで共有したいときは .cargo/config.toml の build.target-dir を使います。

Q. cargo install で入れたコマンドはどこにありますか？ A. $CARGO_HOME/bin、通常は ~/.cargo/bin です。rustup が同じ場所に cargo・rustc も置くため、PATH が通っていれば rg のようにそのまま使えます。一覧は cargo install --list です。

Q. 「cargo: command not found」と出ます。 A. ~/.cargo/bin が PATH に入っていません。rustup のインストール直後ならターミナルを開き直すか、source ~/.cargo/env を実行します。手元で PATH から外して実行すると、同じ文言になりました。

Q. apt の cargo ではいけませんか？ A. 動きますが、Ubuntu 24.04 の候補は 1.75.0 で、rustup の stable（1.97.0）より 22 版前です。新しいクレートの rust-version に引っかかったり、edition 2024 のプロジェクトを開けなかったりします。公式の rustup を使い、rustup update で上げるのが確実です。

Q. features とは何ですか？ A. コンパイル時に機能を出し入れする仕組みです。serde の derive のように、使う人だけが有効にして、使わない人はコンパイル時間と実行ファイルの大きさを節約できます。有効な feature は cargo tree -e features で見られます。

Q. 依存を最新にするにはどうしますか？ A. cargo update で、Cargo.toml の範囲の中で最新に上がります（Cargo.lock が書き換わる）。範囲を超えて上げるときは cargo add 名前@新しい版 か Cargo.toml を書き換えます。先に cargo update --dry-run で何が上がるかを見られます。

Q. ビルドが遅いときの対策はありますか？ A. まず cargo check で確かめ、実行が要るときだけ cargo build にします。依存の初回コンパイルは避けられないため、CI では ~/.cargo/registry と target/ をキャッシュします。開発中に dev が遅ければ [profile.dev] opt-level = 1 が中間になります（手元で篩が 1.35 秒 → 400 ms）。

まとめ

• Cargo は Rust 公式のビルドツール兼パッケージマネージャーで、rustup で Rust と一緒に入る。cargo new → cargo run で最初のプログラムが動く。
• Cargo.toml は人が書く「欲しい範囲」、Cargo.lock は Cargo が書く「実際の版」。迷ったら Cargo.lock はコミットする（The Cargo Book）。
• cargo add でクレートを足し、tree・info・update で調べて上げる。解説と版が違うときはエラーの help: の行に従う。
• --release で素数の数え上げは 7.8 倍速く、サイズは 1/10 になった。速さを測るときは必ず release。
• test・fmt --check・clippy はコミット前と CI の3点セット。ワークスペース・features・install --locked はパッケージやツールが増えてから。

参考・出典

確認日はいずれも 2026年10月29日です。

• The Cargo Book：https://doc.rust-lang.org/cargo/
• The Cargo Book「Cargo.toml vs Cargo.lock」：https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
• The Cargo Book「Frequently Asked Questions」（Why have Cargo.lock in version control?）：https://doc.rust-lang.org/cargo/faq.html
• The Cargo Book「The Manifest Format」：https://doc.rust-lang.org/cargo/reference/manifest.html
• The Cargo Book「Specifying Dependencies」：https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html
• The Cargo Book「Features」：https://doc.rust-lang.org/cargo/reference/features.html
• The Cargo Book「Profiles」：https://doc.rust-lang.org/cargo/reference/profiles.html
• The Cargo Book「Workspaces」：https://doc.rust-lang.org/cargo/reference/workspaces.html
• The Cargo Book「cargo install」：https://doc.rust-lang.org/cargo/commands/cargo-install.html
• Rust 公式「インストール」（rustup・Windows の手順）：https://www.rust-lang.org/ja/tools/install
• crates.io（Rust のパッケージレジストリ）：https://crates.io/
• rust-lang/cargo（GitHub）：https://github.com/rust-lang/cargo

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。