The error error while loading shared libraries: cannot open shared object file: No such file or directory appears on Linux when a program cannot locate a required shared library (.so file) at runtime. It blocks the program from launching entirely.
This error commonly appears after compiling software from source, installing a new application, or moving library files outside the standard system directories. In each case, the dynamic linker searches its known paths and fails to find what it needs.
This guide covers five reliable methods to resolve the error, from a quick cache refresh to a permanent system-wide fix.
What Causes the Shared Library Error
Linux programs do not bundle all their code into a single executable. They rely on shared libraries, reusable collections of functions stored as .so files (similar to .dll files on Windows). The dynamic linker, ld.so, loads these libraries when a program starts.
The linker searches a predefined set of directories. If the required .so file sits outside those directories, or if the linker cache is stale, the program fails with this error.
You can check which libraries a program requires using the ldd command:
ldd /path/to/your/programAny library listed as not found in the output is the source of the problem.
Method 1: Run ldconfig to Refresh the Linker Cache
The fastest fix for this error is running ldconfig. This command rebuilds the dynamic linker’s cache, making any newly installed libraries immediately visible to the system.
Run it with superuser privileges:
sudo ldconfig -vThe -v flag prints verbose output so you can see which directories and libraries the command detects. After it completes, test your program again. If the library was installed but simply not registered in the cache, this step resolves the error without any further changes.
Method 2: Add the Library Path to LD_LIBRARY_PATH
If the library exists on disk but lives in a non-standard directory, you can tell the linker where to find it using the LD_LIBRARY_PATH environment variable. This variable holds a colon-separated list of directories the linker checks before its default paths.
Step 1: Locate the missing .so file. Replace libexample.so with the actual library name from your error message:
sudo find / -name libexample.soNote the full directory path from the output.
Step 2: Export that directory to LD_LIBRARY_PATH. For example, if the library is in /usr/local/lib:
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATHStep 3: Test your program again in the same terminal session.
This change only lasts for the current session. To make it permanent, add the export line to your shell profile file:
echo 'export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrcUse ~/.bash_profile instead if you are on a system that uses that file for login shells.
Method 3: Add the Path to /etc/ld.so.conf (Permanent System-Wide Fix)
For a permanent fix that applies to all users and all sessions, add the library directory to /etc/ld.so.conf. The linker reads this file on every program launch.
Step 1: Open the file with a text editor:
sudo nano /etc/ld.so.confStep 2: Add your library directory on a new line at the bottom. Do not remove any existing entries. The file should look similar to this:
include ld.so.conf.d/*.conf
/usr/local/libStep 3: Save the file and run ldconfig to apply the change:
sudo ldconfigStep 4: Verify the linker now sees your directory and its libraries:
ldconfig -p | grep localYour path and the .so files it contains should appear in the output. This fix survives reboots and applies system-wide.
Method 4: Install the Missing Package
Sometimes the library file is entirely absent from the system. No path configuration helps if the file does not exist. In this case, you need to install the package that provides it.
Step 1: Search your package manager for a package that matches the missing library name. On Debian, Ubuntu, and their derivatives:
apt search libexampleThe library name in the error message and the package name are often different. For example, a missing libzstd.so might be provided by a package named zstd or libzstd-dev. Search broadly if the exact name returns no results.
Step 2: Install the identified package:
sudo apt install package-nameStep 3: After installation, update the linker cache:
sudo ldconfigRun your program again to confirm the fix works.
On RPM-based systems such as Fedora or RHEL, use dnf search and sudo dnf install instead.
Method 5: Set the Library Path at Compile Time with -rpath
If you control the source code and compile the program yourself, you can embed the library path directly into the executable. This approach makes the binary self-sufficient without requiring any system-level configuration.
When compiling with GCC, pass the -Wl,-rpath flag to specify the runtime library path:
gcc your_program.c -o your_program -L/usr/local/lib -Wl,-rpath=/usr/local/lib -lyourlibraryBreaking down the flags:
-L/usr/local/libtells the compiler where to find the library during compilation.-Wl,-rpath=/usr/local/libpasses the-rpathargument to the linker, embedding the search path into the final binary.-lyourlibrarylinks against the library (replace with the actual library name, without thelibprefix and.soextension).
After compiling, run the binary directly. The linker reads the embedded path and finds the library without needing LD_LIBRARY_PATH or any entries in ld.so.conf.
Which Method Should You Use
| Situation | Recommended Fix |
|---|---|
| Newly installed library not detected | Method 1: sudo ldconfig |
| Library in a custom directory, temporary fix | Method 2: LD_LIBRARY_PATH |
| Library in a custom directory, permanent fix | Method 3: /etc/ld.so.conf |
| Library file missing from the system | Method 4: Install the package |
| You compile the program yourself | Method 5: -rpath at compile time |
Start with Method 1 in most cases. If the library is confirmed installed but the error persists, move to Method 3 for a clean permanent solution. If ldd shows the library as not found and it does not exist anywhere on disk, Method 4 is the correct path.
