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.

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:
error: linking with `cc` failed: exit status: 1
= note: rust-lld: error: unable to find library -losipparser2
collect2: error: ld returned 1 exit statusOther 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:
# .cargo/config.toml — keep lld, add the missing search path
[target.x86_64-unknown-linux-gnu]
rustflags = ["-Clink-arg=-L/usr/local/lib"]# .cargo/config.toml — opt out of the lld default
[target.x86_64-unknown-linux-gnu]
rustflags = ["-Clinker-features=-lld"]# one-off, to confirm the diagnosis
RUSTFLAGS="-Clinker-features=-lld" cargo build -vCore 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:
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# 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 librariesThe 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
| Setting | Linker used | Search paths | Typical outcome |
|---|---|---|---|
| default before 1.90 | system ld via cc | the distro's built-in list | /usr/local/lib found |
| default from 1.90 (rustup) | rust-lld via cc -fuse-ld=lld | only what the driver passes | /usr/local/lib missed |
-Clinker-features=-lld | system ld again | built-in list | previous behaviour |
-Clinker=clang | clang's default linker | clang's configuration | varies by distro |
-Clinker=rust-lld | rust-lld directly | none | many missing -l errors |
| distro rustc (apt, dnf) | distro's choice, often no rust-lld | distro list | unchanged by the release |
| Symptom | Likely cause | Check |
|---|---|---|
rust-lld: error: unable to find library -lX | library outside the passed paths | find / -name 'libX.*' |
error: linker 'cc' not found | no C toolchain in the image | which cc gcc |
linking with clang failed with -lc | wrong sysroot for the target | target triple and --target |
works with cargo run, fails in cargo test | different features or extra cdylib | cargo test -v |
| fails only in CI cache | stale target/ from the old linker | cargo 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:
# .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.
2. Build scripts that emit link search paths
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:
// 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:
cargo build --target x86_64-unknown-linux-musl --release
file target/x86_64-unknown-linux-musl/release/app
# statically linkedIf 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:
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 --releaseFor 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:
[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:
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-llddirectly. It skips the driver and loses every default path. - Assuming
ld.so.confaffects linking. It configures the runtime loader only. - Adding
-Lafter the-lit should apply to. Order matters for lld. - Blaming the crate. A crate that emits its own link search paths usually still works.
- Forgetting
cargo cleanin CI after changing link settings. Cached objects hide the effect. - Installing a
-devpackage and expecting the linker to find it in a custom prefix. Pass the path. - Mixing a distro rustc with rustup's
rust-lldexpectations. Checkwhich rustcfirst. - Shipping an image without
cc. The error names it plainly; installbuild-essentialin 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 documentationThe Rust documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Rust work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Rust guides
All Rust guidesRust: failed to run custom build command for openssl-sys
The build script could not find OpenSSL headers. Read its output, install the development package, point pkg-config at the prefix, or vendor the library.
Cargo: failed to select a version for a requirement
Candidates exist but none match, or two requirements cannot unify. Read the graph before touching Cargo.lock.
Rust 2024 edition: static mut references and if-let drop order
Edition 2024 denies shared references to static mut and drops if-let temporaries earlier. Both are silent until the build or a deadlock changes.
Rust E0277: the trait bound is not satisfied
The compiler names a trait, a type and a span. Implement, derive, or change the call; never guess the conversion Rust refuses to make.
More in Rust
All Rust guidesThe guides filed next to this one in Rust, in library order.