Error 'cannot open shared object file': causes and solution

What Does the "cannot open shared object file" Error Mean?

The error with the text error while loading shared libraries: <library_name>.so: cannot open shared object file: No such file or directory (or its variants, such as ld-linux.so not found) is a critical message from the Linux dynamic loader (ld-linux.so or ld.so).

It means the system failed to find the required shared library (a file with the .so extension) during an attempt to run an executable file (a program, utility, or other binary). The dynamic loader is responsible for resolving a program's dependencies on external libraries. If the required file is not found in the specified paths, the launch is aborted.

Full text of a typical error:

./myapp: error while loading shared libraries: libssl.so.1.1: cannot open shared object file: No such file or directory

Here, libssl.so.1.1 is the missing library.

Causes

1. The library is not installed. The most common cause. The program requires a specific version of a library (e.g., libssl.so.1.1), which is absent from the system.
2. The library is installed but in a non-standard path. The loader searches for libraries only in paths specified in /etc/ld.so.conf and files in /etc/ld.so.conf.d/, as well as standard locations (/lib, /usr/lib). If the library is located, for example, in /opt/custom/lib, it will not be found.
3. The loader cache (/etc/ld.so.cache) is outdated. Even if the library is in the correct place, the loader uses a compiled cache. After installing a new library, the cache must be updated with the ldconfig command.
4. Package conflict or corruption. The library may have been removed or corrupted during the update/removal of another package.
5. Architecture or glibc version incompatibility. Attempting to run a 32-bit program on a purely 64-bit system without installing 32-bit libraries (:i386 packages in Debian/Ubuntu). Or, a program compiled for a very old/new version of a library that doesn't exist in the current distribution release.
6. Broken symbolic links. In the library directories, there may be broken links like libssl.so -> libssl.so.1.1 pointing to a non-existent file.

Solutions

Solution 1: Update the loader cache (simplest and most common)

This is the first and mandatory step after installing any new library.

1. Open a terminal.
2. Execute the command with superuser privileges:

   sudo ldconfig
   

3. Try running the program again.

What ldconfig does: It scans all directories listed in configuration files /etc/ld.so.conf and /etc/ld.so.conf.d/*.conf, finds libraries there (lib*.so* files), updates (or creates) the cache /etc/ld.so.cache, and updates symbolic links. After this, the loader knows where to find all installed libraries.

💡 Tip: If you just installed a package via a package manager (apt, dnf), it usually calls ldconfig itself. But if you manually copied a .so file to /usr/local/lib — you must run ldconfig.

Solution 2: Install the missing package

If the library does not physically exist on the system, it needs to be installed.

For Debian/Ubuntu and derivatives:

1. Find the package name that provides the needed library. The most accurate way:

   apt-file search libssl.so.1.1 | head -n 5
   

   
   If apt-file is not installed, first run sudo apt update && sudo apt install apt-file && sudo apt-file update.
2. Install the package (example for libssl.so.1.1):

   sudo apt update
   sudo apt install libssl1.1
   

   
   Or, if a newer version is required:

   sudo apt install libssl3
   

3. Update the cache: sudo ldconfig.

For CentOS/RHEL/Fedora/Rocky/AlmaLinux:

1. Find the package:

   yum provides "*/libssl.so.1.1"
   # or for dnf
   dnf provides "*/libssl.so.1.1"
   

2. Install the found package (e.g., openssl-libs):

   sudo dnf install openssl-libs
   

3. Update the cache: sudo ldconfig.

Solution 3: Add a non-standard path to ld.so configuration

If the library is in a custom folder (e.g., you compiled and installed a program in /opt/myapp/lib).

1. Create a new configuration file (recommended) or edit an existing one:

   sudo nano /etc/ld.so.conf.d/custom-apps.conf
   

   
   Add one line with the full path to the folder containing the .so files:

   /opt/myapp/lib
   

   
   You can add multiple paths, each on a new line.
2. Apply the changes:

   sudo ldconfig
   

3. Verify the path was added to the cache:

   ldconfig -p | grep myapp
   

⚠️ Important: Do not add paths to temporary or untrusted directories in /etc/ld.so.conf. This is a security matter.

Solution 4: Use the LD_LIBRARY_PATH environment variable (temporary workaround)

This method has the highest priority for the loader but is considered temporary and less secure, as it can lead to loading the wrong libraries.

1. Set the environment variable before running the command:

   LD_LIBRARY_PATH="/path/to/library_folder:$LD_LIBRARY_PATH" ./your_program
   

   
   Example:

   LD_LIBRARY_PATH="/home/user/app/lib:$LD_LIBRARY_PATH" ./myapp
   

2. For permanent use (only for the current user), add a line to ~/.bashrc or ~/.profile:

   export LD_LIBRARY_PATH="/home/user/app/lib:$LD_LIBRARY_PATH"
   

   
   After that, run source ~/.bashrc or log out and back in.

⚠️ Warning: Avoid global (system-wide) use of LD_LIBRARY_PATH in /etc/profile. It can break system utilities. Use it only for specific applications or in user scripts.

Solution 5: Reinstall or configure RPATH for a specific binary (advanced)

If you are developing or managing a specific application, you can embed the library search path directly into the binary using the patchelf utility.

1. Install patchelf:

   # Debian/Ubuntu
   sudo apt install patchelf
   # CentOS/RHEL/Fedora
   sudo dnf install patchelf
   

2. Check the current RPATH (embedded library search path) of the binary:

   patchelf --print-rpath ./your_program
   

3. Set the desired RPATH (e.g., $ORIGIN/lib to search in a lib folder next to the binary):

   patchelf --set-rpath '$ORIGIN/lib' ./your_program
   

4. Now the binary will look for libraries in the specified relative path, regardless of system settings.

Prevention

• Install packages only from your distribution's official repositories. This guarantees library compatibility.
• Do not remove system libraries manually. Always use the package manager (apt remove, dnf remove).
• After manually installing software (from source, to /usr/local) always run sudo ldconfig if the installer did not do it.
• Use isolated environments (e.g., conda, virtualenv for Python, docker containers, flatpak, snap) for applications with non-standard dependencies. This prevents them from conflicting with system libraries.
• When compiling from source, use flags like ./configure --prefix=/usr/local (or another clean path) and then make install. Standard paths (/usr/local/lib) are already accounted for in ld.so.conf.d.
• Update your system periodically (sudo apt update && sudo apt upgrade, sudo dnf upgrade) to receive current and compatible library versions.