ldconfig: Refresh the Shared Library Cache
ldconfig rebuilds the /etc/ld.so.cache so the dynamic linker can find shared libraries you installed outside the standard paths.
After copying a .so into /usr/local/lib or a custom directory, binaries still fail to load it until ldconfig refreshes the cache. This is a frequent cause of "not found" at runtime.
What it does
ldconfig scans the directories in /etc/ld.so.conf and /etc/ld.so.conf.d/, plus the trusted defaults /lib and /usr/lib, and rebuilds /etc/ld.so.cache. The dynamic linker consults this cache to resolve shared library dependencies at program start.
Common usage
# after installing a lib into a custom dir
echo "/usr/local/lib" > /etc/ld.so.conf.d/local.conf
ldconfig
# check whether a library is now known to the linker
ldconfig -p | grep libsslOptions
| Flag | What it does |
|---|---|
| (no args) | Rebuild the cache from configured directories |
| -p | Print the current cache contents |
| -n <dir> | Process only the given directory, no cache rebuild |
| -v | Verbose: show directories scanned and links created |
| /etc/ld.so.conf.d/*.conf | Extra library search paths, one per line |
In CI
When a Dockerfile installs a library into a nonstandard prefix, add its directory under /etc/ld.so.conf.d and run ldconfig, or set LD_LIBRARY_PATH. Package installs via apt or dnf usually run ldconfig for you; manual copies do not.
Common errors in CI
"error while loading shared libraries: libX.so.1: cannot open shared object file: No such file or directory" means the linker cannot find the library; add its directory and run ldconfig, or check ldconfig -p. "is not a symbolic link" warnings from ldconfig are usually harmless. A library present on disk but still not found means its directory is not in ld.so.conf.d and ldconfig has not indexed it.
Using this in CI
A runner shell is not a login shell. It does not read your dotfiles, it usually has no TTY, and by default it does not stop on the first error, so a failing command in the middle of a multi-line run block can leave the job green.
# make the shell behave the way you assume it does
- name: Build
shell: bash
run: |
set -euo pipefail # exit on error, undefined vars, and pipeline failures
./do-the-thing | tee out.log