Fixing Rust "link.exe not found" on Windows: Understanding the MSVC Linker

By the end of this page, you will understand why Rust on Windows sometimes fails with link.exe not found, what a linker does, how the MSVC Rust toolchain depends on Microsoft C++ build tools, and the practical ways to fix the problem so cargo run works correctly.

Rust compilation on Windows often involves more than just the Rust compiler.

When you run:

cargo run

Cargo does roughly two major jobs:

1. Compiles your Rust source code into object files
2. Links those object files into a final executable program

That second step is where your error happens.

What is a linker?

A linker is a tool that combines compiled pieces of code into a final .exe file. Rust can compile your code, but on Windows the final executable often depends on a platform-specific linker.

Why link.exe specifically?

Your installed Rust toolchain is likely the MSVC toolchain, such as:

x86_64-pc-windows-msvc

The msvc part means Rust expects to use Microsoft's build tools, including the Microsoft linker:

link.exe

If that linker is not installed or not available in your environment, compilation fails even for a tiny program like Hello World.

Why this matters

This is a common beginner issue on Windows because installing Rust alone may not be enough for the MSVC target. You also need the Windows-native C/C++ build tools that Rust relies on.

In real programming, this matters because:

• Rust projects may depend on native system libraries
• Cross-platform builds use different toolchains on different systems
• Build errors are often caused by missing external tools, not incorrect Rust syntax

So the problem is not your Rust code. The problem is that the build environment is incomplete for the toolchain you selected.

Think of building a Rust program like building a house:

• Rust compiler = workers who create the parts
• Object files = the walls, doors, and windows
• Linker = the crew that assembles everything into the final house

Your Hello World code is fine. The workers finished their part. But the final assembly crew is missing.

On Windows with the MSVC toolchain, that assembly crew is link.exe.

So link.exe not found means:

• Rust started the build
• Rust compiled the code
• Rust tried to assemble the final .exe
• The required Windows linker was not available

Core idea

You write Rust code as usual:

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

Then you build or run it with Cargo:

cargo build
cargo run

But on Windows, the build also depends on the selected target toolchain.

Check your Rust toolchain

Run:

rustup show

You may see something like:

Default host: x86_64-pc-windows-msvc
active toolchain
----------------
stable-x86_64-pc-windows-msvc (default)

If you see msvc, Rust expects Microsoft's linker tools.

Typical fix: install Visual Studio Build Tools

Install the Microsoft C++ build tools that include the linker.

Commonly needed components:

• Desktop development with C++
• MSVC build tools
• Windows SDK

After installation, open a new terminal and try:

cargo run

Alternative: use the GNU toolchain

In some setups, developers use the GNU toolchain instead of MSVC.

Example:

rustup toolchain install stable-x86_64-pc-windows-gnu
rustup default stable-x86_64-pc-windows-gnu

This uses a different linker toolchain, not link.exe.

Example workflow

rustup show
cargo build -v

If the output mentions windows-msvc and fails on link.exe, the issue is almost certainly missing MSVC build tools, not broken Rust source code.

Consider this program:

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

And this command:

cargo run

What happens step by step

1. Cargo reads your project

Cargo checks Cargo.toml and src/main.rs.

2. Rust compiles the source code

rustc turns your Rust code into compiled object files.

At this point, your source code is valid.

3. Cargo starts the linking stage

Rust now needs to create the final executable, such as:

helloworld.exe

4. Rust looks for the configured linker

Because your target is likely:

x86_64-pc-windows-msvc

Rust expects the Microsoft linker:

link.exe

5. The linker is missing

Windows returns:

The system cannot find the file specified. (os error 2)

That means the executable link.exe is not installed or not accessible from the current build environment.

6. Build stops

Since the final executable cannot be created, Cargo reports:

error: Could not compile `helloworld`.

Important takeaway

The Rust code is not the issue. The failure happens after compilation, during the final assembly step.

This concept appears in many real Rust projects on Windows.

1. Building command-line tools

A simple CLI app may compile fine on Linux or macOS but fail on Windows if the required linker is missing.

2. Projects with native dependencies

Some Rust crates depend on C or system libraries. In these cases, correct linker setup becomes even more important.

Examples include:

• database drivers
• graphics libraries
• cryptography libraries
• system integration crates

3. CI and build automation

In automated pipelines, builds fail if the machine has Rust installed but lacks the matching linker or SDK.

4. Team development on Windows

One developer may have Visual Studio Build Tools installed, while another only installed Rust. The second developer may hit link.exe not found immediately.

5. Cross-platform applications

Teams often need to understand which platform toolchain is used on each operating system:

• Linux: usually gcc or clang
• macOS: usually Apple toolchain
• Windows MSVC: link.exe
• Windows GNU: GNU linker tools

In real projects, developers usually solve this in one of these ways.

Install and standardize the required toolchain

Teams often document setup steps such as:

• install Rust with rustup
• install Visual Studio Build Tools with C++ support
• verify with rustup show
• run cargo build

This is common in onboarding guides and README files.

Use environment-specific guard checks

Build scripts and setup scripts often check whether expected tools exist before starting a full build.

For example, teams may verify:

• active target triple
• whether link.exe is available
• whether the Windows SDK is installed

Prefer consistent targets across a team

A project may standardize on one Windows target:

• x86_64-pc-windows-msvc for native Microsoft toolchain compatibility
• x86_64-pc-windows-gnu if the team prefers GNU tools

Error diagnosis with verbose output

Developers often use:

cargo build -v

This helps confirm which linker Cargo is trying to invoke.

Configuration patterns

Some codebases include .cargo/config.toml settings for custom linkers or targets when the environment is not default. This is useful, but beginners should first make sure the standard linker setup works correctly.

1. Thinking the Rust code is wrong

Your Hello World program is valid.

Broken assumption:

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

This code is not the problem.

How to avoid it

If the error mentions link.exe, gcc, ld, or another external tool, the issue is probably the build environment, not your syntax.

2. Installing Rust but not C++ build tools

Many beginners assume Rust includes every required Windows build tool.

How to avoid it

If using the MSVC target, install Visual Studio Build Tools with C++ components.

3. Not checking the active toolchain

You may think you are using GNU when you are actually using MSVC.

How to avoid it

Run:

rustup show

Check the active target carefully.

4. Installing tools but not reopening the terminal

Sometimes the tools are installed, but your current terminal session does not see updated environment variables.

How to avoid it

Close the terminal, open a new one, and retry cargo run.

5. Mixing toolchains without understanding them

For example, switching targets randomly can create confusion.

Potentially confusing commands:

rustup default stable-x86_64-pc-windows-msvc
rustup default stable-x86_64-pc-windows-gnu

How to avoid it

Choose one toolchain intentionally and make sure its matching linker tools are installed.

6. Assuming cargo clean will fix missing tools

cargo clean removes build artifacts, but it does not install link.exe.

cargo clean
cargo run

This will not solve a missing linker problem unless the environment issue was fixed separately.

MSVC vs GNU on Windows

Compiler vs linker

cargo build vs cargo run

Error source comparison

Quick reference

Check active Rust toolchain

rustup show

Look for:

x86_64-pc-windows-msvc

If you see msvc, Rust expects Microsoft's linker.

Build or run

cargo build
cargo run

Verbose diagnostics

cargo build -v

Common cause of link.exe not found

• Rust MSVC toolchain is installed
• Visual C++ build tools are missing
• or terminal environment does not see them

Usual fix

Install Microsoft C++ build tools, including:

• MSVC compiler tools
• Windows SDK
• Desktop development with C++ workload

Alternative approach

Use GNU toolchain instead:

rustup toolchain install stable-x86_64-pc-windows-gnu
rustup default stable-x86_64-pc-windows-gnu

Key rule

If the error mentions the linker, your Rust source code may be perfectly correct.

Good troubleshooting order

1. Run rustup show
2. Check whether target is msvc
3. Install required build tools
4. Open a new terminal
5. Run cargo build -v again

Why does Rust need link.exe on Windows?

If you are using the MSVC target, Rust relies on Microsoft's linker to create the final executable.

Is my Hello World code wrong?

No. The code is valid. The problem is the missing linker tool, not the Rust source.

How do I know whether I am using MSVC or GNU?

Run rustup show. The target triple will include either msvc or gnu.

What should I install to fix link.exe not found?

Install Visual Studio Build Tools or Visual Studio with the C++ workload and Windows SDK.

Can I avoid link.exe completely?

Yes, by using the GNU Rust target on Windows. However, that changes the toolchain and may affect compatibility.

Why did Rust install successfully if building still fails?

Rust itself installed correctly, but the selected Windows toolchain also depends on external system build tools.

Does cargo clean fix this error?

No. cargo clean removes build artifacts, but it does not install a missing linker.

Should I reinstall Rust?

Usually not. First verify your toolchain and install the matching linker tools.

• Rust toolchains — Important because Rust can target different platforms and linkers.
• Cargo build process — Helps you understand compile, link, and run stages.
• Target triples — Explains names like x86_64-pc-windows-msvc.
• Compilers vs linkers — Clarifies why code can compile but still fail to build.
• Environment variables — Useful because installed tools may not be visible in the current terminal.
• Visual Studio Build Tools — Common Windows dependency for native compilation.
• Cross-platform development — Shows why different operating systems use different toolchains.