skip to content

A program links cleanly with g++ -L/opt/geo/lib -lgeo but fails at startup because libgeo.so cannot be found; why, and how do rpath and runpath fix it?

level: seniorimportance: should knowfreq 52%

answer

  1. link time is not run time
  2. the loader never sees -L
  3. NEEDED records a name
  4. $ORIGIN makes bundles relocatable
  5. RUNPATH yields to LD_LIBRARY_PATH

basics

~20 s

-L only tells the linker where to find libraries while linking; the executable records just the library's name. At startup the dynamic loader searches its own path list, so embed one with -Wl,-rpath or install the library where the loader looks.

solid answer

~40 s

Linking and loading are separate searches. `-L/opt/geo/lib` only adds a directory for the **link-time** search; the linker then records a `NEEDED` entry with the library's name (its soname, such as `libgeo.so.1`), not its path. At startup the **dynamic loader** looks for that name in its own list: `RPATH` entries in the binary (only if it has no `RUNPATH`), `LD_LIBRARY_PATH`, `RUNPATH` entries, the loader cache built by `ldconfig`, then default directories such as `/lib` and `/usr/lib`. `/opt/geo/lib` is in none of them, so the program dies with a cannot-open-shared-object error. Fixes: link with `-Wl,-rpath,/opt/geo/lib`, or `-Wl,-rpath,'$ORIGIN/../lib'` for a relocatable bundle; install into a standard directory and run `ldconfig`; or set `LD_LIBRARY_PATH` for development only. `RUNPATH` applies only to the binary's own direct dependencies and can be overridden by `LD_LIBRARY_PATH`; `RPATH` cannot.

code

bash · 5 lines
bash
g++ -fPIC -shared -Wl,-soname,libgeo.so.1 geo.o -o lib/libgeo.so.1
ln -sf libgeo.so.1 lib/libgeo.so
g++ main.o -L lib -lgeo -Wl,-rpath,'$ORIGIN/../lib' -o bin/app
readelf -d bin/app | grep -E 'NEEDED|RPATH|RUNPATH'
ldd bin/app | grep geo

go deeper

for a junior

Know that linking finds libraries with -L but running needs the dynamic loader to find them too.

for a middle

Explain NEEDED entries and sonames, and fix a missing library with an rpath, ldconfig or LD_LIBRARY_PATH.

for a senior

Choose between RPATH and RUNPATH, ship $ORIGIN-relative bundles, and diagnose with readelf, ldd and LD_DEBUG, including transitive dependencies.

for a principal

Set the deployment rule for how products find their libraries, so no release depends on a developer's environment variables.

## Two searches, two programs A dynamically linked program meets its libraries twice: 1. **At link time**, the linker (run by `g++`) must find `libgeo.so` to check that every symbol resolves. `-L/opt/geo/lib` adds a directory to this search, and the GCC manual describes `-L` only as adding a directory to the list searched for `-l`. 2. **At run time**, the **dynamic loader** maps the library into the process. It never sees the link command, so `-L` has no effect here. What connects the two is the `NEEDED` entry the linker writes into the executable: the library's **soname**, for example `libgeo.so.1`, without a directory. If the loader cannot find that name, the program fails before `main` runs, with an error saying it cannot open the shared object file. ## Where the dynamic loader looks On a glibc-based Linux system the loader searches, in this order: | Step | Source | Set by | |---|---|---| | 1 | `DT_RPATH` entries, **used only when there is no `DT_RUNPATH`** | `-Wl,-rpath,dir` with old-style tags | | 2 | `LD_LIBRARY_PATH` environment variable | the user or a wrapper script | | 3 | `DT_RUNPATH` of the object needing the library | `-Wl,-rpath,dir` with `--enable-new-dtags` | | 4 | the loader cache | `ldconfig` and `/etc/ld.so.conf` | | 5 | default directories such as `/lib` and `/usr/lib` | the system | `-Wl,-rpath,dir` stores `dir` in the binary; whether it lands as `RPATH` or `RUNPATH` depends on the linker's configuration, and `-Wl,--enable-new-dtags` or `-Wl,--disable-new-dtags` chooses explicitly. The two differ in two ways that matter: - `LD_LIBRARY_PATH` **overrides `RUNPATH`** but not `RPATH`. - `RUNPATH` applies only to the object's **own direct dependencies**. If `libgeo.so` itself needs `libproj.so` from the same directory, `libgeo.so` needs its own `RUNPATH`, or the library must be found some other way. ## $ORIGIN: relocatable bundles `$ORIGIN` in an rpath expands to the directory containing the object being loaded. `-Wl,-rpath,'$ORIGIN/../lib'` lets an application shipped as `bin/app` plus `lib/libgeo.so.1` run from any install location. Quote it so the shell does not expand `$ORIGIN`, and write `$$ORIGIN` inside a Makefile. ## Diagnosing - `ldd ./app` lists each needed library and where the loader would find it, or `not found`. It may run the program's loader, so use it only on binaries you trust. - `readelf -d ./app` shows `NEEDED`, `RPATH` or `RUNPATH`, and `readelf -d libgeo.so.1` shows its `SONAME`. - `LD_DEBUG=libs ./app` makes glibc's loader print every directory it tries. ## Choosing a fix 1. **System package**: install into a standard directory, or add a file under `/etc/ld.so.conf.d`, and run `ldconfig`. Nothing is baked into the binary. 2. **Self-contained bundle**: link with `-Wl,-rpath,'$ORIGIN/../lib'` and ship the libraries beside the program; give each bundled library its own `$ORIGIN` runpath for its dependencies. 3. **Fixed install prefix**: `-Wl,-rpath,/opt/geo/lib` works but ties the binary to that path. 4. **Development only**: `LD_LIBRARY_PATH`. It leaks into child processes and overrides `RUNPATH`, so it is a poor production mechanism. ## A worked failure 1. `./bin/app` exits immediately; the loader reports that it cannot open `libgeo.so.1`. 2. `readelf -d bin/app` shows `NEEDED libgeo.so.1` and no `RPATH` or `RUNPATH`, so the loader only tries `LD_LIBRARY_PATH`, its cache and the default directories. 3. `ldd bin/app` confirms `libgeo.so.1 => not found`. 4. The library sits in `/opt/geo/lib`, which none of those mention. Relink with `-Wl,-rpath,/opt/geo/lib`, or move the library and use `$ORIGIN`. 5. Rerun `ldd`: the line now points at the file, and the program starts. The same steps diagnose the second classic variant: the program loads **a different** `libgeo.so.1` than intended, found earlier in the search order, and then fails with a missing symbol or behaves oddly. `LD_DEBUG=libs` shows which directory won. ## The soname Build the library with `-Wl,-soname,libgeo.so.1` and install the file as `libgeo.so.1.4.2` with symlinks `libgeo.so.1` (what the loader opens) and `libgeo.so` (what `-lgeo` finds at link time). Executables then depend on the major version, not on a build-specific file name.

  • Why can a program find libgeo.so through RUNPATH but still fail on libproj.so, which libgeo needs?
    `RUNPATH` applies only to the direct dependencies of the object that carries it. The executable's `RUNPATH` helps load `libgeo.so`, but when the loader resolves `libgeo.so`'s own `NEEDED` entries it uses `libgeo.so`'s search path, so that library needs its own `$ORIGIN` runpath.
  • What is -Wl,-rpath-link for, and why does it not fix a run-time failure?
    `-rpath-link` tells the GNU linker where to find the dependencies of shared libraries **during the link**, so it can check their symbols. It is not stored in the output, so the dynamic loader never sees it.

  • The -L directory is stored in the executable and used at run time.
  • LD_LIBRARY_PATH is the right way to ship a production application.
  • RUNPATH applies to every library loaded transitively, not just direct dependencies.
  • If the program linked, its shared libraries are guaranteed to load.
  • RPATH and RUNPATH behave identically when LD_LIBRARY_PATH is set.