ldconfig: Usage, Options & Common CI Errors

ldconfig refreshes the linker cache so newly installed shared libraries are found.

After you drop a .so into a non-standard path, the dynamic loader will not find it until ldconfig rebuilds its cache. That missing step is behind many "cannot open shared object file" CI failures.

What it does

ldconfig scans the standard library directories plus those in /etc/ld.so.conf and /etc/ld.so.conf.d/, then rebuilds /etc/ld.so.cache so the dynamic linker can resolve shared libraries quickly. You run it after installing libraries to a new location so binaries can load them at runtime.

Common usage

ldconfig                                         # rebuild the cache
echo /usr/local/lib > /etc/ld.so.conf.d/local.conf && ldconfig
ldconfig -p | grep ssl                            # list cached libraries
ldconfig -p | grep libstdc                        # check a specific lib is found

Common errors in CI

"error while loading shared libraries: libX.so.1: cannot open shared object file: No such file or directory" after installing a lib to /usr/local/lib (or a custom prefix) means the loader cache is stale - add the dir to /etc/ld.so.conf.d/ and run ldconfig (or set LD_LIBRARY_PATH as a quick fix). ldconfig -p is the diagnostic: if the lib is absent from its output, the loader will not find it. On Alpine (musl) ldconfig behaves differently and there is no ld.so.conf.d in the glibc sense.

Options

Related guides