Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

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.

~5 min readRust
#Rust#Cargo#OpenSSL#Docker
A rust crate pulling a native library crate through a pkg-config probe, amber missing openssl plate, cyan prebuilt crate

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-dev and pkg-config on Debian and Ubuntu, openssl-devel on Fedora, openssl-dev and pkgconf on Alpine.
  • Point the build at the install. PKG_CONFIG_PATH for Homebrew or a custom prefix, or OPENSSL_DIR when the crate cannot find the .pc file.
  • Vendor it. openssl = { version = "0.10", features = ["vendored"] } compiles OpenSSL from source and needs perl, make and a C compiler, but removes the system dependency entirely.
Build script lineMeaningFix
could not find system library 'openssl'No .pc file visibleInstall -dev package, or set OPENSSL_DIR
pkg-config exited with status code 1pkg-config ran and found nothingpkg-config --libs openssl to see why
openssl.pc needs to be installedRuntime library present, headers missingInstall the development package
error: failed to run custom build command aloneWrapper messageScroll to the --- stdout block
cannot find -lssl at link timeLibrary present, wrong path or archOPENSSL_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 build
text
error: 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' crate

The fix inside the same image:

bash
apt-get update && apt-get install -y pkg-config libssl-dev cargo build

Key Comparison Table

The package name is the most common stumble, and it differs on every distribution.

DistributionPackagesPrefix
Debian / Ubuntupkg-config libssl-dev/usr
Fedora / RHELpkgconf-pkg-config openssl-devel/usr
Alpinepkgconf openssl-dev/usr
Archpkgconf 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.

StrategyNeeds system OpenSSLBuild timeUse when
System libraryYes, with headersFastServers you control, CI images with the package
vendored featureNoSlow, compiles OpenSSLStatic binaries, cross builds, musl
rustls insteadNo, no C at allFastYou 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:

bash
cargo build -vv 2>&1 | grep -A30 "openssl-sys" pkg-config --libs --cflags openssl

The 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.

dockerfile
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 --release

That 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:

bash
export OPENSSL_DIR="$(brew --prefix openssl@3)" export PKG_CONFIG_PATH="$OPENSSL_DIR/lib/pkgconfig" cargo build

OPENSSL_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.

toml
[dependencies] openssl = { version = "0.10", features = ["vendored"] } reqwest = { version = "0.12", default-features = false, features = ["rustls-tls"] }
bash
cargo build --target x86_64-unknown-linux-musl

vendored 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:

toml
[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:

bash
OPENSSL_DIR=/usr/local/openssl \ OPENSSL_STATIC=1 \ cargo build --release ldd target/release/app | grep ssl

An 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 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.