Linux 'library-not-found' Error: Causes and 5 Fixes

What the "library-not-found" Error Means

The library-not-found error (often seen as error while loading shared libraries: libxxx.so: cannot open shared object file: No such file or directory) occurs when the Linux dynamic linker (ld.so) cannot locate a required shared library (a file with the .so extension) at runtime.

Typical scenario: You try to run a compiled application or script and receive a message like this instead of execution:

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

The system found the myapp executable, but it requires the libssl.so.1.1 library to function, which is not in the paths the linker checks.

Common Causes

1. Missing library package. The most frequent cause. The required package (e.g., libssl-dev or openssl) is not installed on the system.
2. Library is installed but in a non-standard path. The dynamic linker, by default, searches for libraries only in /lib, /usr/lib, /usr/local/lib, and their architecture-specific subdirectories (e.g., /usr/lib/x86_64-linux-gnu). If the library resides in /opt/lib or a home directory, it won't be found.
3. Architecture mismatch. You are trying to run a 32-bit application, but only the 64-bit version of the library is installed (or vice versa).
4. Corrupted or incomplete package installation. Library files may have been deleted or damaged.
5. Outdated library version. The application requires a specific version (e.g., libssl.so.1.1), while the system has a newer (libssl.so.3) or older version installed. Symbolic links may be misconfigured.
6. Missing ldconfig step. After manually installing a library into a standard path, the linker's cache must be updated.

Solutions

Method 1: Install the Missing Package via Package Manager (Recommended)

This is the most correct and systematic approach, as the package manager handles dependencies, paths, and cache updates automatically.

1. Identify the missing package. Use the ldd command on the problematic executable. It will list all dependencies and mark those that are not found.

   ldd /path/to/your/executable
   

   
   Example output:

   linux-vdso.so.1 (0x00007ffd5b9f8000)
   libssl.so.1.1 => not found
   libcrypto.so.1.1 => not found
   libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f8c1a000000)
   /lib64/ld-linux-x86-64.so.2 (0x00007f8c1a400000)
   

   
   Here, packages providing libssl.so.1.1 and libcrypto.so.1.1 are missing.
2. Find the package containing the library. For Debian/Ubuntu, use apt-file. Install it first if necessary: sudo apt update && sudo apt install apt-file. Then update the database and search:

   sudo apt-file update
   apt-file search libssl.so.1.1
   

   
   The output will contain lines like:

   libssl1.1: /usr/lib/x86_64-linux-gnu/libssl.so.1.1
   libssl1.1: /usr/lib/x86_64-linux-gnu/libssl.so.1.1.0
   

   
   The package name is libssl1.1.
   For RHEL/CentOS/Fedora, use yum provides or dnf provides:

   yum provides "*/libssl.so.1.1"
   

   
   For Arch Linux:

   pacman -Fy libssl.so.1.1
   

3. Install the found package.
   • Debian/Ubuntu:

     sudo apt install libssl1.1
     

   • RHEL/CentOS 7/8:

     sudo yum install openssl-libs
     

   • Fedora:

     sudo dnf install openssl-libs
     

   • Arch Linux:

     sudo pacman -S openssl
     

4. Update the linker cache (usually done automatically on package install, but for completeness):

   sudo ldconfig
   

5. Run the application again. The error should be resolved.

Method 2: Manual Library Installation from Source

If the required library version is not available in your distribution's repositories, you can install it manually.

1. Download the library's source code from the official website or GitHub (e.g., for OpenSSL: https://www.openssl.org/source/).
2. Extract the archive and navigate into the directory:

   tar -xzf openssl-1.1.1w.tar.gz
   cd openssl-1.1.1w
   

3. Configure, compile, and install. Typically, the /usr/local prefix is used (a standard path already in ldconfig's cache). For a 64-bit system:

   ./config --prefix=/usr/local --openssldir=/usr/local/openssl shared
   make -j$(nproc)
   sudo make install
   

   The shared flag is crucial—it builds shared libraries (.so), not just static ones (.a).
4. Update the cache:

   sudo ldconfig
   

5. Verify the library file exists: ls -l /usr/local/lib/libssl.so.1.1.

Method 3: Add a Non-Standard Path via LD_LIBRARY_PATH

If the library already exists on the system but resides in a non-standard location (e.g., you installed it to ~/mylibs), you can temporarily "tell" the linker where to look.

1. Set the LD_LIBRARY_PATH environment variable. Prepend the path to the directory containing the libraries:

   export LD_LIBRARY_PATH=/home/your_user/mylibs:$LD_LIBRARY_PATH
   

   • Important: The path must point to the directory containing the .so files, not to the file itself.
   • This setting only affects the current shell session. For a permanent effect, add the line to ~/.bashrc, ~/.zshrc, or ~/.profile.
2. Launch the application from the same terminal session. It will now be able to find the libraries.
3. For debugging, you can see which paths are checked using ldd (it will now account for LD_LIBRARY_PATH) or LD_DEBUG=libs ./your_application.

Method 4: Create Symbolic Links (symlinks)

If you have the correct version of the library but it has a different name (e.g., libssl.so.1.1.0 instead of libssl.so.1.1), create a symlink.

1. Find the actual library file:

   sudo find /usr -name "libssl.so*" 2>/dev/null
   

   
   Example output: /usr/lib/x86_64-linux-gnu/libssl.so.1.1.0.
2. Create a symlink in a directory already in the cache (e.g., /usr/lib/x86_64-linux-gnu/):

   cd /usr/lib/x86_64-linux-gnu
   sudo ln -s libssl.so.1.1.0 libssl.so.1.1
   sudo ln -s libcrypto.so.1.1.0 libcrypto.so.1.1  # if needed for that too
   

3. Update the cache:

   sudo ldconfig
   

Method 5: Rebuild the Application with Correct Paths

If you are compiling an application from source yourself, ensure the linker knows where to find libraries during the build.

1. Install the -dev/-devel packages. These contain header files (.h) and symlinks for compilation (e.g., libssl-dev for OpenSSL).

   sudo apt install libssl-dev  # Debian/Ubuntu
   sudo yum install openssl-devel  # RHEL/CentOS
   

2. Use compiler flags during the build. Typically, pkg-config automatically inserts the correct paths:

   gcc myapp.c -o myapp $(pkg-config --cflags --libs openssl)
   

   
   Or specify them explicitly:

   gcc myapp.c -o myapp -I/usr/include/openssl -L/usr/lib/x86_64-linux-gnu -lssl -lcrypto
   

   • -I — path to headers.
   • -L — path to libraries (during linking).
   • -l — library name without the lib prefix and .so extension.
3. The built application will then look for libraries in standard system paths, making a library-not-found error unlikely.

Prevention

• Use package managers (apt, yum, pacman) to install libraries. They guarantee proper placement and dependency tracking.
• Check dependencies before building. For C/C++ programs, use pkg-config --exists <library> or check for header files (#include <lib.h>).
• Document custom paths. If you install libraries in non-standard locations (e.g., /opt/), be sure to document this and configure LD_LIBRARY_PATH or add configuration files to /etc/ld.so.conf.d/ (after which sudo ldconfig is required).
• Update your system regularly: sudo apt update && sudo apt upgrade. This helps avoid version conflicts.
• Before running a third-party binary file, check its dependencies with ldd and ensure all libraries are found (=> /path/to/file instead of => not found).

💡 Tip: To permanently add a non-standard path (e.g., /usr/local/lib) to ld.so's search path, create a configuration file:

echo "/usr/local/lib" | sudo tee /etc/ld.so.conf.d/usr-local.conf
sudo ldconfig

This is a cleaner solution than using LD_LIBRARY_PATH globally.