# How to Initialize Rustlings Exercises: What `rustlings init` Does

> Learn how to initialize Rustlings exercises with rustlings init. Discover how this command sets up your workspace by extracting files, creating a Cargo workspace, and scaffolding solution directories.

- Repository: [The Rust Programming Language/rustlings](https://github.com/rust-lang/rustlings)
- Tags: how-to-guide
- Published: 2026-03-05

---

**The `rustlings init` command creates a self-contained Rustlings workspace in a `rustlings/` directory by extracting embedded exercise files, generating a Cargo workspace configuration, and scaffolding solution directories.**

When you want to start learning Rust with the official rust-lang/rustlings repository, you initialize your local environment using the `rustlings init` subcommand. This command does not clone the entire repository; instead, it unpacks exercise files that are embedded directly into the binary, sets up a Cargo workspace, and prepares a directory structure for tracking your progress.

## The Initialization Workflow in Detail

The entry point for the command is in [`src/main.rs`](https://github.com/rust-lang/rustlings/blob/main/src/main.rs), which parses the `Init` subcommand and delegates to the implementation in [`src/init.rs`](https://github.com/rust-lang/rustlings/blob/main/src/init.rs). The function executes an 11-step workflow:

### 1. Detect Existing Installations

The command first checks if a `rustlings/` directory already exists in the current working directory. If found, it aborts immediately with `RUSTLINGS_DIR_ALREADY_EXISTS_ERR` to prevent accidental overwrites.

```rust
// init.rs:27-31
if Path::new("rustlings").exists() {
    return Err(RUSTLINGS_DIR_ALREADY_EXISTS_ERR);
}

```

### 2. Validate Cargo Workspace Context

The tool executes `cargo locate-project --workspace` to determine if the current directory resides within a Cargo workspace. If the command succeeds, the tool verifies that a `[workspace]` section exists in the root [`Cargo.toml`](https://github.com/rust-lang/rustlings/blob/main/Cargo.toml). This detection logic spans lines 32-86 in [`src/init.rs`](https://github.com/rust-lang/rustlings/blob/main/src/init.rs).

### 3. User Confirmation

Before making any changes, the tool displays a description of the impending operation and waits for the user to press **Enter**. This prompt is defined in [`src/term.rs`](https://github.com/rust-lang/rustlings/blob/main/src/term.rs) and invoked at `init.rs:87-90`.

### 4. Register Workspace Member (Conditional)

When running inside an existing Cargo workspace, the command temporarily creates a package using `cargo new rustlings --vcs none`. This registers the directory as a workspace member in Cargo's internal metadata. The command then immediately removes this temporary directory (lines 91-108), as the actual files will be created in subsequent steps.

### 5. Create the Directory Structure

If not operating within a workspace context, the command simply creates the `rustlings/` directory using standard filesystem operations (`init.rs:119-121`).

### 6. Populate Exercise Files

The command loads the master exercise list by parsing [`info.toml`](https://github.com/rust-lang/rustlings/blob/main/info.toml) via `InfoFile::parse()` defined in [`src/info_file.rs`](https://github.com/rust-lang/rustlings/blob/main/src/info_file.rs). It then extracts every exercise file from the binary's embedded assets (`EMBEDDED_FILES.init_exercises_dir`) and writes them to `rustlings/exercises/` (`init.rs:123-126`).

### 7. Scaffold Solution Directories

To help track progress, the command creates a `solutions/` directory containing a README and subdirectories mirroring the exercise structure. Each subdirectory receives a placeholder solution file (`INIT_SOLUTION_FILE`) that learners will fill in (`init.rs:128-145`).

### 8. Generate Workspace Configuration

The command takes the embedded template [`dev-Cargo.toml`](https://github.com/rust-lang/rustlings/blob/main/dev-Cargo.toml), strips its comment header, and augments it with all exercise crates using the `updated_cargo_toml` helper from [`src/cargo_toml.rs`](https://github.com/rust-lang/rustlings/blob/main/src/cargo_toml.rs). This generates the final [`Cargo.toml`](https://github.com/rust-lang/rustlings/blob/main/Cargo.toml) that defines the workspace (`init.rs:147-160`).

### 9. Configure Development Environment

Auxiliary files are written to optimize the development experience: [`rust-analyzer.toml`](https://github.com/rust-lang/rustlings/blob/main/rust-analyzer.toml) for IDE configuration, `.gitignore` for version control, and [`.vscode/extensions.json`](https://github.com/rust-lang/rustlings/blob/main/.vscode/extensions.json) recommending helpful VS Code extensions (`init.rs:162-170`).

### 10. Initialize Git Repository

If the command did not create a temporary Cargo workspace member (step 4), it runs `git init` inside the new `rustlings/` directory. Errors during this step are intentionally ignored (`init.rs:172-180`).

### 11. Completion

Finally, the command prints "Initialization done ✓" in green and displays the `POST_INIT_MSG` hint explaining how to begin the exercises (`init.rs:182-189`).

## Generated Directory Structure

After running `rustlings init`, your directory contains:

```text
rustlings/
├─ Cargo.toml                # generated workspace manifest

├─ rust-analyzer.toml
├─ .gitignore
├─ .vscode/
│   └─ extensions.json
├─ exercises/                # all exercise source files (embedded)

│   ├─ 01_variables/
│   │   └─ variables1.rs
│   └─ …
└─ solutions/
    ├─ README.md
    ├─ 01_variables/
    │   └─ variables1.rs   # placeholder solution file

    └─ …

```

## Working with the Initialized Workspace

Once initialized, navigate into the directory and use Cargo to interact with the exercises:

```bash
$ cd rustlings
$ cargo run -- check        # verifies all exercises, marking them done/pending

$ cargo run -- run         # executes the next pending exercise

$ cargo run -- hint        # displays a hint for the next pending exercise

```

These commands rely on the state and structure created by `rustlings init`, specifically the [`info.toml`](https://github.com/rust-lang/rustlings/blob/main/info.toml) exercise index and the workspace configuration generated in [`src/init.rs`](https://github.com/rust-lang/rustlings/blob/main/src/init.rs).

## Summary

- **`rustlings init`** creates a local `rustlings/` directory without cloning the repository, using files embedded in the binary itself.
- The command detects existing directories and Cargo workspaces to avoid conflicts and properly register the new member.
- It generates a complete Cargo workspace configuration, scaffolds solution directories, and configures IDE support via [`rust-analyzer.toml`](https://github.com/rust-lang/rustlings/blob/main/rust-analyzer.toml).
- Exercise files are extracted from `EMBEDDED_FILES.init_exercises_dir` and written to the `exercises/` directory based on the [`info.toml`](https://github.com/rust-lang/rustlings/blob/main/info.toml) manifest.
- The initialization process is fully self-contained and concludes with a success message and instructions for starting the exercises.

## Frequently Asked Questions

### What happens if I run `rustlings init` in an existing Cargo workspace?

The command detects the workspace context by running `cargo locate-project --workspace`. If a `[workspace]` section exists in the root [`Cargo.toml`](https://github.com/rust-lang/rustlings/blob/main/Cargo.toml), the tool temporarily creates a `rustlings` package using `cargo new` to register the directory as a workspace member, then removes the temporary files before creating the actual exercise structure.

### Does `rustlings init` clone the Rustlings repository?

No. The command does not perform a `git clone` of the rust-lang/rustlings repository. Instead, it extracts exercise files that are embedded directly into the binary at compile time via `EMBEDDED_FILES.init_exercises_dir`. This makes the initialization fast and self-contained, requiring only the `rustlings` binary and a Rust toolchain.

### Where are the exercise files stored before initialization?

The exercise files and metadata are embedded into the `rustlings` binary as static assets. When you run `rustlings init`, the command parses the embedded [`info.toml`](https://github.com/rust-lang/rustlings/blob/main/info.toml) manifest and writes the files from `EMBEDDED_FILES.init_exercises_dir` to the local `rustlings/exercises/` directory on your filesystem.

### Can I customize the `rustlings/` directory name?

No, the directory name is hardcoded as `rustlings` throughout the initialization logic in [`src/init.rs`](https://github.com/rust-lang/rustlings/blob/main/src/init.rs). The command specifically checks for the existence of a `rustlings/` directory and will abort with `RUSTLINGS_DIR_ALREADY_EXISTS_ERR` if it finds one. To use a different directory name, you would need to initialize in a different parent directory and then rename the folder manually after initialization.