Rust: 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.

Introduction & Quick Summary
error: failed to run custom build command for openssl-sys is Cargo reporting that a dependency's build script exited non-zero. Open ~/.cargo logs or scroll up: the real message is inside the build script output, usually The system library 'openssl' required by crate 'openssl-sys' was not found or pkg-config exited with status code 1. The crate needs either a system OpenSSL with a .pc file or a vendored copy it can compile itself, and it found neither.
Three fixes cover nearly every case:
- Install the development package.
libssl-devandpkg-configon Debian and Ubuntu,openssl-develon Fedora,openssl-devandpkgconfon Alpine. - Point the build at the install.
PKG_CONFIG_PATHfor Homebrew or a custom prefix, orOPENSSL_DIRwhen the crate cannot find the.pcfile. - Vendor it.
openssl = { version = "0.10", features = ["vendored"] }compiles OpenSSL from source and needsperl,makeand a C compiler, but removes the system dependency entirely.
| Build script line | Meaning | Fix |
|---|---|---|
could not find system library 'openssl' | No .pc file visible | Install -dev package, or set OPENSSL_DIR |
pkg-config exited with status code 1 | pkg-config ran and found nothing | pkg-config --libs openssl to see why |
openssl.pc needs to be installed | Runtime library present, headers missing | Install the development package |
error: failed to run custom build command alone | Wrapper message | Scroll to the --- stdout block |
cannot find -lssl at link time | Library present, wrong path or arch | OPENSSL_LIB_DIR, or vendored |
Core Mechanics, Signatures & Reproducible Setup
openssl-sys is a -sys crate: it contains no Rust logic for OpenSSL itself, only FFI declarations plus a build.rs that discovers the library. Its search order is OPENSSL_DIR, then pkg-config, then common install prefixes. If none yields headers and libraries, the build script exits with status 101, and Cargo prints only the wrapper error.
pkg-config is a small tool with its own search path. PKG_CONFIG_PATH adds directories that contain .pc files, and the file records Cflags and Libs with the prefix baked in. That is why a Homebrew install on Apple Silicon is invisible by default: the prefix is /opt/homebrew, and pkg-config looks in /usr/local/lib/pkgconfig unless told otherwise.
Reproduce it in a container without the development package:
docker run --rm -v "$PWD":/app -w /app rust:1.82 cargo new demo --bin
cd demo && cargo add openssl
cargo builderror: failed to run custom build command for `openssl-sys v0.9.104`
Caused by:
process didn't exit successfully: `/app/demo/target/debug/build/openssl-sys-.../build-script-main` (exit status: 101)
--- stdout
cargo:rerun-if-env-changed=OPENSSL_DIR
run pkg_config fail: `pkg-config --libs --cflags openssl` did not exit successfully
error: could not find system library 'openssl' required by the 'openssl-sys' crateThe fix inside the same image:
apt-get update && apt-get install -y pkg-config libssl-dev
cargo buildKey Comparison Table
The package name is the most common stumble, and it differs on every distribution.
| Distribution | Packages | Prefix |
|---|---|---|
| Debian / Ubuntu | pkg-config libssl-dev | /usr |
| Fedora / RHEL | pkgconf-pkg-config openssl-devel | /usr |
| Alpine | pkgconf openssl-dev | /usr |
| Arch | pkgconf openssl | /usr |
| macOS (Homebrew) | brew install openssl@3 | /opt/homebrew/opt/openssl@3 |
Three strategies exist for the dependency itself, and the choice affects portability more than build time.
| Strategy | Needs system OpenSSL | Build time | Use when |
|---|---|---|---|
| System library | Yes, with headers | Fast | Servers you control, CI images with the package |
vendored feature | No | Slow, compiles OpenSSL | Static binaries, cross builds, musl |
rustls instead | No, no C at all | Fast | You do not need OpenSSL-specific behaviour |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
Read the build script output first
Cargo's wrapper hides the cause. Get the full output with one command before changing anything:
cargo build -vv 2>&1 | grep -A30 "openssl-sys"
pkg-config --libs --cflags opensslThe second command is the same probe the build script runs. If it prints Package openssl was not found in the pkg-config search path, the crate is right and the environment is missing the package or the path.
Fix the environment, not the crate
On Debian and Ubuntu, the runtime package libssl3 is not enough; the headers live in libssl-dev. On Alpine, pkgconf is a separate package from pkg-config, which surprises CI images that install only the latter.
FROM rust:1.82-slim
RUN apt-get update \
&& apt-get install -y --no-install-recommends pkg-config libssl-dev \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY . .
RUN cargo build --releaseThat Dockerfile is the smallest reproducible fix, and keeping it in the repository prevents the next base-image bump from reintroducing the failure.
Homebrew on Apple Silicon
brew install openssl@3 puts the library under /opt/homebrew/opt/openssl@3, outside the default pkg-config path, and macOS also ships LibreSSL headers that are not OpenSSL. Export the path for the build:
export OPENSSL_DIR="$(brew --prefix openssl@3)"
export PKG_CONFIG_PATH="$OPENSSL_DIR/lib/pkgconfig"
cargo buildOPENSSL_DIR alone is often enough, because the build script derives lib and include from it. Set both when a transitive dependency uses pkg-config directly.
Cross-compilation and musl
A cross build cannot use the host's pkg-config: it would return host libraries for a target binary. The reliable answer is the vendored feature, which compiles OpenSSL with the target's toolchain.
[dependencies]
openssl = { version = "0.10", features = ["vendored"] }
reqwest = { version = "0.12", default-features = false, features = ["rustls-tls"] }cargo build --target x86_64-unknown-linux-muslvendored needs perl, make and cc for the target, so a musl build needs musl-tools as well. If the build fails with Can't locate ... in @INC, that is Perl missing a module in a slim image, not an OpenSSL problem.
Prefer rustls when OpenSSL is not required
If nothing in the dependency tree needs OpenSSL-specific features, removing it is better than building it. Most HTTP clients expose a feature for this:
[dependencies]
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }The result is a pure-Rust TLS stack with no .pc file, no system package, and a static binary that runs on scratch. The trade-off is feature parity: rare legacy ciphers and some enterprise TLS inspection setups still require OpenSSL.
Static linking against a system OpenSSL
For a mostly-static binary that must use the system library, tell the crate to link statically and provide the paths explicitly:
OPENSSL_DIR=/usr/local/openssl \
OPENSSL_STATIC=1 \
cargo build --release
ldd target/release/app | grep sslAn empty ldd line for libssl means the static link worked. A missing library at runtime means the binary linked dynamically despite the flag, which usually happens when OPENSSL_LIB_DIR points at a directory with only shared objects.
Common Compilation/Runtime Mistakes & Version Gotchas
Installing the runtime package only. libssl3, openssl or libssl1.1 provide the shared library without headers or .pc files. The development package is the one the build script needs.
Assuming the error is a crate bug. openssl-sys has built successfully for years with the same script; a failure is a missing environment, not a regression. Check cargo tree -i openssl-sys to see which dependency pulls it.
Adding vendored and losing the C toolchain. In a slim image, vendoring fails on cc: not found or perl: not found. Install build-essential and perl alongside it.
Setting PKG_CONFIG_PATH in the wrong shell. Docker build steps, IDE terminals and CI jobs each start fresh. Put the export in the Dockerfile or the CI environment, not in a local ~/.zshrc.
Mixing architectures. A Homebrew prefix for arm64 used in an x86_64 build produces cannot find -lssl at link time, which looks like a missing package. Check file on the library before debugging the crate.
Ignoring the -sys crate version. A dependency pinned to an old openssl-sys may not support the vendored flag combination you chose; cargo update -p openssl-sys first, then change features.
Version floor. The vendored feature exists in openssl 0.10 and later; rustls-tls is available in reqwest 0.11 and later; OpenSSL 3 needs a matching openssl-sys from 2021 onward, so an old lockfile can fail against a modern system library.
The decision order that saves the most time: read the build script output, install the development package, set PKG_CONFIG_PATH if the prefix is non-standard, use vendored for cross builds, and drop OpenSSL entirely when rustls fits. When you edit the feature list, the diff tool shows exactly which flags changed, and the environment variable formatter keeps OPENSSL_DIR and PKG_CONFIG_PATH consistent between the Dockerfile and CI.
Official references: the openssl crate documentation and Cargo's build scripts reference.
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 guidesCargo: 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 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.
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.