---
title: "Starting a Rust project with Cargo"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source: https://iinventedlight.com/library/notes/rust-cargo-new-project.md
source_license: "MIT / Apache-2.0; restated in our own words"
attribution: "Summary by iinventedlight (AI-assisted). Sources: The Rust Project, Hello, Cargo!, MIT / Apache-2.0; The Rust Project, Creating a New Package, MIT / Apache-2.0."
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 2026-11-03
status: published
checked_on: 2026-11-03
as_of: 2026-11-03
confidence: medium
untested: "Cargo was not run; cargo new, build, run, check, and release builds were not executed; only the fetched book pages were read."
category: coding-references
topic_area: "Rust with Cargo"
tags: rust, cargo, packages, build
sources:
  - id: S1
    title: "Hello, Cargo!"
    publisher: The Rust Project
    url: https://doc.rust-lang.org/book/ch01-03-hello-cargo.html
    accessed: 2026-11-03
    license: "MIT / Apache-2.0"
  - id: S2
    title: "Creating a New Package"
    publisher: The Rust Project
    url: https://doc.rust-lang.org/cargo/guide/creating-a-new-project.html
    accessed: 2026-11-03
    license: "MIT / Apache-2.0"
---
# Starting a Rust project with Cargo

## Summary
Cargo builds Rust code, downloads dependencies, and builds those libraries. A new package is `cargo new`, a Cargo.toml manifest, and source under src. Use cargo check while editing, cargo run to try the program, and cargo build --release for the optimized binary.

## Create the package
Official installers include Cargo. `cargo --version` prints a version when it is present. `cargo new hello_cargo` creates that directory with Cargo.toml and src/main.rs, and starts a Git repo unless you are already in one. Pass `--bin` for a program and `--lib` for a library. `--vcs none` skips version control. `cargo init` writes a manifest for code you already have if you move it under src.

Cargo.toml is TOML. `[package]` holds the name, version, and edition. Both pages show version 0.1.0 and edition 2024 on a new package. `[dependencies]` lists other packages, called crates. The generated main prints a hello-world line. Source belongs in src. The top directory is for a README, license, and configuration, not for code.

The first `cargo build` also writes Cargo.lock, which pins exact dependency versions. Leave it for Cargo to edit. With no dependencies the file is sparse.

## Build, check, run
`cargo build` writes a debug binary to target/debug/hello_cargo, or target\debug\hello_cargo.exe on Windows. Debug is the default: it compiles faster and runs slower because optimizations are off. `cargo run` builds if sources changed, then runs the binary. If nothing changed, it skips the compile. `cargo check` stops before producing an executable, so it is faster while you are still editing. Build for real when you need the file.

`cargo build --release` optimizes and writes target/release instead of target/debug. It compiles more slowly and runs faster. Benchmark that binary, not the debug one. The same three commands work on every operating system. For someone else's project, clone it, enter the directory, and run cargo build. Cargo pays off once there is more than one file or a dependency. Starting with it means adding a dependency later is the normal step.

## Claims
- id: C1
  claim: Cargo builds your code, downloads the libraries it depends on, and builds those libraries.
  source: S1
  evidence: "Cargo handles a lot of tasks for you, such as building your code, downloading the libraries your code depends on, and building those libraries."
- id: C2
  claim: cargo new creates a project directory plus a Cargo.toml file and a src directory that contains main.rs.
  source: S1
  evidence: "Cargo has generated two files and one directory for us: a Cargo.toml file and a src directory with a main.rs file inside."
- id: C3
  claim: cargo check confirms the project compiles without producing an executable, and it is often faster than cargo build for that reason.
  source: S1
  evidence: "cargo check is much faster than cargo build because it skips the step of producing an executable."
- id: C4
  claim: A release build uses optimizations and writes the binary under target/release rather than target/debug.
  source: S1
  evidence: "This command will create an executable in target/release instead of target/debug ."
- id: C5
  claim: cargo new starts a package; pass --bin for a program and --lib for a library.
  source: S2
  evidence: "To start a new package with Cargo, use cargo new"
- id: C6
  claim: Cargo.toml is the manifest and holds the metadata Cargo needs in order to compile the package.
  source: S2
  evidence: "This is called a manifest , and it contains all of the metadata that Cargo needs to compile your package."