Fixing Rust "linker 'cc' not found" on Debian in WSL

By the end of this page, you will understand why Rust sometimes fails with linker 'cc' not found on Debian in WSL, what the cc linker is used for, and how to fix the problem by installing the system C toolchain that Rust depends on during compilation.

Rust does not always produce a final executable entirely by itself. In many cases, rustc compiles your Rust source code into object files and then asks a system linker to combine them into a runnable program.

On Linux systems such as Debian, that linker is usually accessed through the cc command. Even if Rust itself is installed correctly through rustup, the operating system still needs standard build tools installed.

When you see:

error: linker `cc` not found

it usually means:

• Rust is installed
• rustc is working
• but the system C compiler and linker tools are missing

On Debian, these tools are commonly installed through packages such as:

• build-essential
• gcc
• libc6-dev

This matters because Rust programs often need the system linker to:

• produce the final executable
• link against the C standard library and system libraries
• build crates that include C dependencies or native extensions

So the problem is not usually with Rust itself. It is usually with the Linux development tools that Rust expects to exist on the machine.

Think of Rust compilation as a two-stage assembly process:

1. Rust builds the program parts
2. The linker joins those parts into one finished executable

rustc is like a machine that manufactures the pieces.

cc is like the worker who bolts those pieces together into a final product.

If the worker is missing, the pieces may be created, but the final product cannot be assembled. That is why Rust reports a linker error even though installation seemed successful.

The usual fix on Debian or Debian-based systems is to install the standard build tools.

sudo apt update
sudo apt install build-essential

This package group typically installs:

• gcc
• g++
• make
• development libraries needed for linking

After that, try compiling again.

Example

Create a small Rust file:

fn main() {
    println!("Hello, Rust!");
}

Compile it:

rustc main.rs

Run it:

./main

If the linker tools are installed correctly, the program should compile and run.

Check whether cc exists

You can verify whether the command is available:

cc --version

If it was missing before, installing build-essential should make it available.

You can also check where it is located:

which cc

Typical output might be:

/usr/bin/cc

Consider this Rust program:

fn main() {
    println!("Hi");
}

When you run:

rustc main.rs

this roughly happens:

1. rustc reads main.rs
2. Rust checks the syntax and type rules
3. Rust generates lower-level compiled object code
4. Rust calls the system linker through the cc command
5. The linker combines compiled Rust code with required system libraries
6. A final executable is produced

If cc is missing, the process fails at step 4.

So the failure does not mean your Rust code is wrong. It means the final system-level tool needed to finish the build is not installed.

Typical fix flow

Run these commands:

sudo apt update
sudo apt install build-essential

Then test again:

rustc main.rs
./main

If it works, the issue was the missing linker toolchain.

This issue appears in real projects whenever a language toolchain depends on system compilers.

Rust application development

Rust binaries on Linux often need the system linker to produce executables.

Cargo builds

Even if rustc is installed, cargo build may fail for the same reason because Cargo eventually calls Rust compilation and linking steps.

Native dependencies

Some crates compile C or C++ code behind the scenes. These require system build tools even more clearly.

Examples include crates related to:

• database drivers
• compression libraries
• cryptography
• image processing
• FFI bindings

WSL development setups

WSL feels like a normal Linux environment, but it starts minimal. Many developer tools that are preinstalled on full Linux desktops are missing until you install them manually.

CI and containers

This same error often appears in Docker containers or CI pipelines where Rust is installed but packages like gcc or build-essential were forgotten.

In real projects, developers usually treat the Rust toolchain and the system build toolchain as separate setup requirements.

Common patterns include:

Environment bootstrap scripts

Teams often document setup steps such as:

sudo apt update
sudo apt install build-essential pkg-config
curl https://sh.rustup.rs -sSf | sh

This avoids linker errors on fresh machines.

Dockerfiles

Rust projects commonly install OS build tools before building:

RUN apt-get update && apt-get install -y build-essential pkg-config

Guard checks in setup docs

Projects may ask developers to verify commands like:

rustc --version
cargo --version
cc --version

Native library workflows

When projects use crates that bind to system libraries, developers also install related -dev packages.

For example:

• libssl-dev
• libpq-dev
• libsqlite3-dev

So in real codebases, fixing cc is often the first step in a larger environment setup process.

1. Assuming Rust installation includes the system linker

A common beginner assumption is that rustup installs everything needed to build programs.

It installs Rust tools, but not your Linux system compiler toolchain.

2. Installing only Rust and skipping Debian build tools

Broken setup:

curl https://sh.rustup.rs -sSf | sh
rustc main.rs

Possible result:

error: linker `cc` not found

Fix:

sudo apt install build-essential

3. Confusing WSL with native Windows compilation

If you are inside Debian on WSL, you need Linux packages installed with apt, not Windows compilers installed elsewhere.

Installing Visual Studio on Windows does not automatically provide /usr/bin/cc inside WSL.

4. Forgetting to update package lists first

Sometimes package installation fails or uses stale metadata if you skip:

sudo apt update

5. Checking only rustc --version

This confirms Rust exists, but not that the linker exists.

Also check:

cc --version

6. Manually changing linker settings too early

Beginners sometimes try to configure a custom linker in .cargo/config.toml before installing basic tools.

Usually the simplest fix is just installing the standard Debian toolchain first.

rustup vs apt

WSL vs native Linux

# Install Rust
curl https://sh.rustup.rs -sSf | sh

# Fix missing linker on Debian/WSL
sudo apt update
sudo apt install build-essential

# Check Rust
rustc --version
cargo --version

# Check linker
cc --version
which cc

# Compile a Rust file
rustc main.rs

# Run the output
./main

Key idea

• rustup installs Rust tools
• apt install build-essential installs the Linux build tools Rust needs for linking

Common error

error: linker `cc` not found

Usual cause

• Missing Debian compiler/linker packages

Usual fix

sudo apt install build-essential

If a crate needs extra native libraries

You may also need packages such as:

sudo apt install pkg-config libssl-dev

Why does Rust need cc if I am not writing C code?

Rust often relies on the system linker to produce the final executable, even for pure Rust programs.

What package should I install on Debian to fix linker 'cc' not found?

Usually build-essential is the correct package group to install.

Is this a Rust installation problem?

Usually not. Rust is often installed correctly, but the Debian system compiler toolchain is missing.

Does this happen in WSL often?

Yes. WSL environments are often minimal, so development packages may not be installed by default.

Can I fix this by reinstalling Rust?

Usually no. Reinstalling Rust will not typically install Debian's cc tool.

How do I check whether the fix worked?

Run:

cc --version
rustc main.rs

If both work, the issue is likely resolved.

Do I need gcc or clang?

Either can provide a linker interface in many setups, but on Debian the easiest standard fix is usually installing build-essential, which commonly provides gcc and related tools.

• Rust toolchain — Rust uses tools like rustc, cargo, and rustup during development.
• Linker — The linker combines compiled code into a final executable.
• Compiler toolchain — A full build environment includes compiler, linker, headers, and libraries.
• Cargo — Rust's package manager and build tool also depends on successful linking.
• WSL — Windows Subsystem for Linux behaves like Linux, so Linux packages must be installed inside it.
• Debian package management — apt is used to install required system dependencies.
• Native dependencies — Some Rust crates rely on external C libraries and development headers.