C++

Fix "Cannot Find -l..." — How ld Searches for Libraries, and Where the Path Is Set

A -l option is not a file path. It is a name the linker expands and then hunts for in a short list of directories — and the project directory that holds the library is not one of them by default. This guide builds a two-file library in a lib folder, reproduces the cannot find error, and reads the failure as what it is: a search that never visited the folder. It then fixes the search at each layer it can break — the -L flag, the exact filename, and CMake's find_library — and finishes with the shared-library version of the trap, where adding a .so to the same folder makes the link succeed and the failure reappear when the program starts.

Written November 18, 2026 · Tested with GCC 13.3 · 6 min read

By the end of this guide
  • The library exists, and the link still fails
  • What -lgreet actually asks for
  • Where the linker searches
  • Fix one: put the directory on the search path

What this guide is

Most linker errors in this family name a missing symbol. This one names a missing file, in a compressed spelling that hides which file and where the linker looked. The examples here use C++17, GCC 13.3 and GNU ld 2.42. One small library threads through the whole guide: a header named greet.h and a source file named greet.cpp that together build a library called libgreet, plus a main.cpp that uses it. The library is built into a folder named lib inside the project, which is where real projects put it — and that folder is the whole problem, because nothing in the default link ever looks there.

The header declares one function:

C++
// greet.h
#pragma once
void greet();

The source file defines it:

C++
// greet.cpp
#include "greet.h"
#include <iostream>
void greet() { std::cout << "hello from libgreet\n"; }

The program calls it:

C++
// main.cpp
#include "greet.h"
int main() {
    greet();
    return 0;
}

Build the library as a static archive inside lib, compile the program, and the two halves are both fine:

Terminal
$ g++ -std=c++17 -Wall -Wextra -c greet.cpp -o greet.o
$ mkdir -p lib
$ ar rcs lib/libgreet.a greet.o
$ ls lib
libgreet.a
$ g++ -std=c++17 -Wall -Wextra -c main.cpp -o main.o

Now link in the usual shorthand way, asking for the library by name:

Terminal
$ g++ main.o -lgreet -o prog
/usr/bin/ld: cannot find -lgreet: No such file or directory
collect2: error: ld returned 1 exit status

The file the error is about is visible in the ls output two commands earlier. It exists, it has the expected name, and it sits one folder away from the object file that needs it. The error does not mean the library is missing from the machine. It means the search the linker ran never found it — and to fix the search, the search itself has to be stated exactly.

What -lgreet actually asks for

A -l option does not name a file. It names a pattern the linker fills in. For -lgreet, the linker searches for a file called libgreet.so first and then for one called libgreet.a, in each directory it searches, in turn. The lib prefix and the extension are added by the linker; they are not part of the option, which is why the option is spelled -lgreet for a file called libgreet.a and why asking for -llibgreet would hunt for a file called liblibgreet.so first and then for one called liblibgreet.a.

The match is exact and case-sensitive, because it is a filename match on a case-sensitive filesystem. The same folder, the same archive, and one capital letter produce the identical error:

Terminal
$ g++ main.o -Llib -lGreet -o prog
/usr/bin/ld: cannot find -lGreet: No such file or directory
collect2: error: ld returned 1 exit status

That second failure carries a -Llib flag and still fails, which is what makes it useful: it separates the name cause from the path cause. When the name in the option does not expand to the name of a file that exists, no search path can rescue the link.

Where the linker searches

The directories the linker searches for a -l name come from two places. Directories named with -L are searched first, in the order they are given, and every -L applies to every -l on the command line regardless of where each appears. After those come the default directories, the ones built into the linker for the system. On the machine these examples use, the default list is the SEARCH_DIR line of the linker's verbose output:

Terminal
$ ld --verbose | grep -m1 SEARCH_DIR
SEARCH_DIR("=/usr/local/lib/x86_64-linux-gnu"); SEARCH_DIR("=/lib/x86_64-linux-gnu"); SEARCH_DIR("=/usr/lib/x86_64-linux-gnu"); SEARCH_DIR("=/usr/lib/x86_64-linux-gnu64"); SEARCH_DIR("=/usr/local/lib64"); SEARCH_DIR("=/lib64"); SEARCH_DIR("=/usr/lib64"); SEARCH_DIR("=/usr/local/lib"); SEARCH_DIR("=/lib"); SEARCH_DIR("=/usr/lib"); SEARCH_DIR("=/usr/x86_64-linux-gnu/lib64"); SEARCH_DIR("=/usr/x86_64-linux-gnu/lib");

Read the list for what is not in it. There is no project directory, no current directory, and no lib folder under either. A library installed system-wide by a development package lands in one of these directories, which is why -l works out of the box for installed libraries and fails for the library a project just built for itself. The linker is not refusing to look in the project folder out of caution; the folder was never on its list.

Three different causes therefore produce the same one-line error. The file may not exist at all, because the library was never built or the development package that provides it was never installed. The file may exist under a different name than the option expands to, as the capital-letter case shows. Or the file may exist with exactly the right name in a directory the search never visits, which is the case this guide built on purpose. Each cause has a different fix, and applying the path fix to a name problem — or reinstalling a package for a path problem — changes nothing.

Fix one: put the directory on the search path

For a library that exists with the right name in a project folder, the fix is to add that folder to the search with -L:

Terminal
$ g++ main.o -Llib -lgreet -o prog
$ ./prog
hello from libgreet

Nothing about the library changed. The archive is the same file the first link failed to find; the only difference is that the search now visits its directory. In a build system this flag is the layer to record — a Makefile variable or a CMake link directory — rather than a command to retype, because the next clean build runs the same search again.

Fix two: name the file itself

A -l option is a search request. A path is not. Naming the archive directly on the command line hands the linker the file itself, and no search takes place:

Terminal
$ g++ main.o lib/libgreet.a -o prog2
$ ./prog2
hello from libgreet

This form fits a one-off link against a library in a known place, and it is the form the CMake example in the next section ends up using for the static archive, once find_library has resolved the search to a full path. Its limit is the mirror of its strength: the path is now fixed in the command, so a library that moves breaks the command instead of being found in its new home.

The same fix in CMake: find_library does the searching

A CMake project records the search instead of the flag. find_library runs the same kind of hunt at configure time — the names and directories it is given, plus defaults unless they are switched off — and stores the full path it finds in a cache variable:

CMake
cmake_minimum_required(VERSION 3.28)
project(greet_demo CXX)
add_executable(prog_cmake main.cpp)
find_library(GREET_LIB NAMES greet PATHS "${CMAKE_SOURCE_DIR}/lib" NO_DEFAULT_PATH REQUIRED)
target_link_libraries(prog_cmake PRIVATE ${GREET_LIB})

With this file in the project root, alongside the same main.cpp and the same lib folder, the build links the archive by the path the search recorded:

Terminal
$ cmake -S . -B build
$ cmake --build build
[ 50%] Building CXX object CMakeFiles/prog_cmake.dir/main.cpp.o
[100%] Linking CXX executable prog_cmake
[100%] Built target prog_cmake
$ ./build/prog_cmake
hello from libgreet

Two details of this form matter in practice. REQUIRED makes a failed search a configure error that names the library, instead of a link error later that does not. And because the result is cached, moving the library afterward does not rerun the search on the next configure — the cached path has to be cleared, or the build directory removed, before find_library will look again.

Everything above used the static archive, because it was the only library in the folder. Add a shared build of the same source to the same folder and the meaning of the unchanged commands shifts:

Terminal
$ g++ -std=c++17 -Wall -Wextra -fPIC -shared greet.cpp -o lib/libgreet.so
$ ls lib
libgreet.a
libgreet.so
$ g++ main.o -Llib -lgreet -o prog_so
$ ./prog_so
./prog_so: error while loading shared libraries: libgreet.so: cannot open shared object file: No such file or directory

The link now succeeds, and it succeeds against a different file: in each directory, the linker tries the .so name before the .a name, so the folder that gained a shared library silently changes which library the same -Llib -lgreet command selects. A static archive is copied into the executable at link time, so prog needed nothing at run time. A shared library is only recorded as a dependency — the executable carries the name libgreet.so and the system's runtime loader has to find the file when the program starts. -L is a link-time search path only; it is not passed on as a runtime one, so the loader runs its own, different search, and lib is not on that list either. The diagnosis tool changes with the failure: ldd shows what the loader can and cannot find for an existing executable:

Terminal
$ ldd prog_so | grep greet
    libgreet.so => not found

There are two fixes, for two different intents. To test a program against a library in a project folder without changing the executable, put the folder on the loader's search path for that one run with LD_LIBRARY_PATH:

Terminal
$ LD_LIBRARY_PATH=lib ./prog_so
hello from libgreet

To ship an executable that finds a library kept beside it, record the runtime path in the executable itself at link time with -rpath. The token $ORIGIN stands for the directory the executable is in, so the recorded path moves with the program instead of naming one machine's folders:

Terminal
$ g++ main.o -Llib -lgreet -Wl,-rpath,'$ORIGIN/lib' -o prog_r
$ ./prog_r
hello from libgreet

The quotes around '$ORIGIN/lib' are part of the fix, not decoration: left unquoted in a shell command, $ORIGIN is expanded by the shell itself — to nothing, in a shell that has no such variable — before the linker ever sees it, and the executable records a path of /lib. Quoted, the token reaches the linker intact and the expansion happens at run time, against the directory the executable is actually in. Note the contrast with a fresh CMake build against the shared library: configured in a new build directory once both files exist, find_library picks libgreet.so, and the build-tree executable carries a RUNPATH naming the lib directory, so it runs where it was built. The static CMake build in the previous section needed no such path — the archive was linked by full path and copied in. A hand-written link line gets no RUNPATH added for it, which is why the rpath step surprises people who move from one to the other.

Which fix for which cause

What the checks show Cause Fix
No file named lib<name>.so or lib<name>.a exists anywhere on the machine The library was never built, or its development package was never installed Build or install it first; no flag fixes a file that is not there
The file exists, but its name differs from the expansion of the -l option — different case, an extra lib in the option, a version suffix in the filename Name mismatch Fix the option (or the filename) so the two match exactly; a search path cannot help
The file exists with the right name in a project folder that is not a default directory Search path Add the folder with -L for a direct link, or record the search with find_library in CMake
The library is one the project builds in a known fixed place and the link is a one-off Search path, simplest form Name the file by its path on the command line and skip the search
The link succeeds against a shared library and the program then fails to start, with ldd reporting the library not found Runtime search path — -L never applied at run time LD_LIBRARY_PATH for a test run, or -rpath with $ORIGIN for an executable that keeps its library beside it

Checklist

  • Before changing any flag, expand the option by hand: -l<name> means a file called lib<name>.so, then lib<name>.a. Check that exact filename, case included, against the folder that is supposed to hold it.
  • Before adding a path, read the default search list for your linker and confirm the library's folder is not already on it — and that the folder you are about to add is the one holding the file.
  • Before reinstalling a package to fix this error, check whether the file already exists somewhere on the machine. An existing file makes it a name or path problem, and reinstalling fixes neither.
  • Before concluding a shared-library link is fixed because it links, run the program. Selecting a .so moves the search to run time, where -L no longer applies.
  • Before debugging a program that will not start, run ldd on it. A not found line names the library the loader could not locate, which is a runtime search problem, not a link problem.
  • Before recording a runtime path in an executable, prefer $ORIGIN-relative paths for libraries shipped beside the program, so the pair can move together.

Sources

  • GNU ld, Command-line Options — for -l namespec, the linker searches the library path for lib<namespec>.so before lib<namespec>.a on ELF systems; for -L searchdir, directories given on the command line are searched in the order specified, before the default directories, and all -L options apply to all -l options regardless of order; for -rpath=dir, the directories are passed to the runtime linker and used to locate shared objects at runtime, with $ORIGIN replaced by the directory containing the program.
  • CMake, find_library — the command searches the names and paths it is given plus default locations unless NO_DEFAULT_PATH is given, stores the result of the search in a cache entry, does not repeat a successful search on later calls, and stops with an error when REQUIRED is given and nothing is found.
  • ld.so, Dynamic Loader — for the runtime search the loader runs when a program starts (directories from LD_LIBRARY_PATH are searched before the directories in DT_RUNPATH, and no project folder is in the default path), for LD_LIBRARY_PATH as a per-run loader path, and for $ORIGIN expanding to the directory containing the program in DT_RUNPATH values, which is why the token has to be quoted against the shell.

Keep Exploring