Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Rust 1.90 moved to rust-lld and linking started failing

A linker swap broke the build without a code change. Here is why lld misses /usr/local/lib and how to choose between fixing and opting out.

~4 min readRust
#Rust#Linking#Toolchain#CI
A cargo binary cube linked by a robotic lld arm reaching for a library shelf, amber error marker

Introduction & Quick Summary

Symptom. A crate that linked fine on Rust 1.89 stops linking on 1.90, and the error is about a library nothing in your code mentions:

code
error: linking with `cc` failed: exit status: 1 = note: rust-lld: error: unable to find library -losipparser2 collect2: error: ld returned 1 exit status

Other machines with the same toolchain report error: linking with rust-lld failed or a missing -lc. In a cargo build for a Docker image the failure can also appear as linker 'cc' not found, which is the pre-1.90 message.

Cause. Rust 1.90 made rust-lld, shipped inside the toolchain, the default linker for x86_64-unknown-linux-gnu when rustc comes from rustup. lld does not read default library search paths, nor ld.so.conf: it links exactly the paths the compiler driver passes. A library that lives in /usr/local/lib, a Homebrew prefix or a vendor directory was found by the old system linker's built-in search path and is now invisible.

Fix. Either tell the link path explicitly, or go back to the previous linker deliberately:

toml
# .cargo/config.toml — keep lld, add the missing search path [target.x86_64-unknown-linux-gnu] rustflags = ["-Clink-arg=-L/usr/local/lib"]
toml
# .cargo/config.toml — opt out of the lld default [target.x86_64-unknown-linux-gnu] rustflags = ["-Clinker-features=-lld"]
bash
# one-off, to confirm the diagnosis RUSTFLAGS="-Clinker-features=-lld" cargo build -v

Core Mechanics, Signatures & Reproducible Setup

-Clinker-features accepts +lld and -lld. When the feature is on, rustc invokes cc (or clang) with -fuse-ld=lld, and cc then runs the bundled rust-lld. The compiler driver is still in the middle, so the linker is not called directly: this is why -Clinker=rust-lld fails with a pile of missing libraries, while -Clinker-features=+lld works.

Reproduce it with a library outside the default search path, which is the same shape as the real failure:

bash
mkdir -p /tmp/lldcheck/lib && cd /tmp/lldcheck printf 'void ext(void) {}\n' > ext.c gcc -shared -fPIC -o lib/libext.so ext.c printf 'fn main() { println!("linked"); }\n' > main.rs RUSTFLAGS="-L /tmp/lldcheck/lib -l ext" rustc main.rs -o main_lld # if the driver does not pass -L in a form lld honours: unable to find library -lext RUSTFLAGS="-Clinker-features=-lld -L /tmp/lldcheck/lib -l ext" rustc main.rs -o main_ld ./main_ld && echo ok
bash
# what the toolchain is actually doing rustc -vV | sed -n '/host/p' cargo build -v 2>&1 | grep -E "cc|rust-lld|lld" | head -5 cc -print-search-dirs | grep libraries

The cc -print-search-dirs output is the list of paths the system linker knows about. If your library is not in one of them, nothing was broken by the upgrade; the previous linker was silently searching a directory lld does not.

Key Comparison Table

SettingLinker usedSearch pathsTypical outcome
default before 1.90system ld via ccthe distro's built-in list/usr/local/lib found
default from 1.90 (rustup)rust-lld via cc -fuse-ld=lldonly what the driver passes/usr/local/lib missed
-Clinker-features=-lldsystem ld againbuilt-in listprevious behaviour
-Clinker=clangclang's default linkerclang's configurationvaries by distro
-Clinker=rust-lldrust-lld directlynonemany missing -l errors
distro rustc (apt, dnf)distro's choice, often no rust-llddistro listunchanged by the release
SymptomLikely causeCheck
rust-lld: error: unable to find library -lXlibrary outside the passed pathsfind / -name 'libX.*'
error: linker 'cc' not foundno C toolchain in the imagewhich cc gcc
linking with clang failed with -lcwrong sysroot for the targettarget triple and --target
works with cargo run, fails in cargo testdifferent features or extra cdylibcargo test -v
fails only in CI cachestale target/ from the old linkercargo clean

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Vendor libraries under /usr/local/lib

This is the canonical case: a library installed from source, or by Homebrew on Linux, lands in /usr/local/lib, which the old ld searched and lld does not. Adding the path through rustflags is the smallest change:

toml
# .cargo/config.toml [target.x86_64-unknown-linux-gnu] rustflags = ["-Clink-arg=-L/usr/local/lib"]

Prefer this over editing ld.so.conf, which only affects the dynamic loader at runtime and nothing at link time.

A -sys crate usually calls cargo:rustc-link-search=native=.... That works with lld too, because Cargo passes it as -L, so a crate that broke with 1.90 is more likely reading a path from pkg-config that the old linker guessed:

rust
// build.rs println!("cargo:rustc-link-search=native=/opt/vendor/lib"); println!("cargo:rustc-link-lib=dylib=osipparser2");

When the crate sets the path itself and still fails, check the ordering: a -L after the -l it should apply to is not used by lld, and rustflags ordering is not always what you expect.

3. Static musl builds and -static-pie

x86_64-unknown-linux-musl builds often add -C target-feature=+crt-static. With self-contained linking, the toolchain does not need a system cc at all for pure-Rust code, and mixing that with a custom -Clinker reintroduces the dependency:

bash
cargo build --target x86_64-unknown-linux-musl --release file target/x86_64-unknown-linux-musl/release/app # statically linked

If a -sys crate needs C, musl's musl-gcc wrapper is the compiler, and CC_x86_64_unknown_linux_musl selects it.

4. Containers: the linker that is not there

A rust:1.90-slim-style image without build-essential has no cc, and the error names it. Install the toolchain in the builder stage, or use a target that self-contains linking:

dockerfile
FROM rust:1.90-bookworm AS build RUN apt-get update && apt-get install -y --no-install-recommends build-essential pkg-config \ && rm -rf /var/lib/apt/lists/* WORKDIR /src COPY . . RUN cargo build --release

For a fully static binary, clux/muslrust or the musl target avoids the glibc dependency entirely, at the cost of a second target in the toolchain.

5. Deciding between opt-out and opt-in

Two teams reach opposite conclusions here, and both are defensible. Opting out (-Clinker-features=-lld) restores yesterday's behaviour and buys time for a proper fix, at the cost of link speed and a divergence from the default every new contributor gets. Opting in means adding the search paths the old linker used to guess, which is where the project belongs in the long run:

toml
[target.x86_64-unknown-linux-gnu] rustflags = ["-Clink-arg=-L/usr/local/lib", "-Clink-arg=-L/opt/vendor/lib"]

Record the reason in the file, because the next person will otherwise delete it as noise.

6. Confirming which toolchain you have

The change applies to rustup-distributed rustc only, so a distro package manager's rustc may behave differently on the same machine:

bash
which rustc rustc -vV | grep -E "host|release" rustup show active-toolchain 2>/dev/null || echo "not a rustup toolchain"

If which rustc points at /usr/bin/rustc, the release notes for 1.90 do not apply directly, and the problem is more likely a missing -dev package than lld.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Setting -Clinker=rust-lld directly. It skips the driver and loses every default path.
  • Assuming ld.so.conf affects linking. It configures the runtime loader only.
  • Adding -L after the -l it should apply to. Order matters for lld.
  • Blaming the crate. A crate that emits its own link search paths usually still works.
  • Forgetting cargo clean in CI after changing link settings. Cached objects hide the effect.
  • Installing a -dev package and expecting the linker to find it in a custom prefix. Pass the path.
  • Mixing a distro rustc with rustup's rust-lld expectations. Check which rustc first.
  • Shipping an image without cc. The error names it plainly; install build-essential in the builder stage.

Check the exact flags a build used with the environment file inspector when they come from CI secrets or a .cargo/config.toml, and compare two toolchain configurations with the text diff tool.

Reference: the Rust 1.90.0 release notes on the lld default, and the linker-features codegen option.

Official references

primary documentation

The Rust documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Rust work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Rust guides

More in Rust

All Rust guides

The guides filed next to this one in Rust, in library order.