Alright, let’s get our hands dirty and create something. You’ve got two tools for kicking off a new Rust project: cargo new and cargo init. One is for the organized, forward-thinking you; the other is for the “I’m already in a directory and just had a brilliant, impulsive idea” you. We’ll cover both, because frankly, both versions of you are valid.

cargo new: The Standard Operating Procedure

This is the command you’ll use 99% of the time. It’s the polite, well-mannered way to start a project. It creates a new directory with everything neatly set up inside. The basic syntax is:

cargo new my_awesome_project

Run that, and you’ll get a new directory called my_awesome_project with the following structure:

my_awesome_project/
├── Cargo.toml
└── src/
    └── main.rs

Let’s break down what you just got, because it’s not just random files—it’s a carefully curated starter pack.

  • Cargo.toml: This is the project’s manifest. It’s the résumé and recipe for your code. It defines your project’s name, version, dependencies, and all sorts of metadata. cargo new pre-populates it with sensible defaults. Open it up. See that [package] section? That’s your project’s ID. The [dependencies] section is where you’ll list all the external crates (libraries) your project needs to import. It starts blissfully empty.
  • src/main.rs: This is the entry point for a binary application. The cargo new command gives you a free “Hello, world!” because the Rust gods aren’t monsters. It’s a perfect little sample to verify everything works.
fn main() {
    println!("Hello, world!");
}

You can immediately run this:

cd my_awesome_project
cargo run

Your terminal should obediently compile and run the program, outputting those two beautiful words. Congratulations, you’re a Rust programmer. Told you it was easy.

You can also specify if you want to create a library project instead of a binary. Libraries don’t have a main() function as an entry point; they’re meant to be used by other programs.

cargo new my_cool_library --lib

This creates a src/lib.rs file instead of main.rs. The structure and Cargo.toml are otherwise identical. The lib.rs file will contain a simple test module, which is a hint about how Rust does testing (a topic for another day).

cargo init: For the Chaos Makers

Now, cargo init is for when you’ve already created a directory, cd’d into it, and then decided it should be a Rust project. Maybe you were setting up a project folder for notes and had an epiphany. Instead of moving back out and using cargo new, you can just run:

# You're already in your desired project directory
cargo init

This does the exact same thing as cargo new, but it does it in the current directory. It creates the Cargo.toml and the src directory with the main.rs file right where you are.

Why would you use this? It’s a minor convenience, but it fits certain workflows, especially if you’re initializing a project inside an existing repository structure. The biggest pitfall here is obvious: if you run cargo init in the wrong directory, you’ll spew project files all over a place you didn’t intend to. Don’t do that. Always double-check your pwd.

The Name Game: picking your project name

Here’s a fun quirk: cargo new will name the directory whatever you tell it to, but it will also use that name as the default name field in Cargo.toml. This name is important—it’s how your crate will be identified if you publish it.

Rust has strict naming conventions for crates. They must only use alphanumeric characters or underscores (_). No hyphens! If you want to create a project with a multi-word name, you must use underscores for the directory and Cargo.toml name.

# This is GOOD and PROPER
cargo new my_brilliant_project

# This is BAD and will cause you pain later
cargo new my-brilliant-project

Why? Because the crate name my-brilliant-project would be invalid; hyphens aren’t allowed. So cargo will helpfully convert it to my_brilliant_project for the Cargo.toml name field, but the directory will still have a hyphen. This creates a frustrating inconsistency between your directory name and your crate name. Just avoid hyphens from the start. Use underscores. Your sanity will thank you.

So, that’s it. new for a fresh start in a new folder, init for committing to the chaos of your current one. Both give you the same solid, sensible foundation. Now go build something.