gcc/g++ "fatal error: X.h: No such file or directory"

By Kaveh Alemi·Latchkey

The compiler could not find a header you #included. Either the library’s development package is not installed, or the directory holding the header is not on the include search path.

What this error means

Compilation stops at the #include line with "fatal error: <header>: No such file or directory" and "compilation terminated." It often passes locally where the -dev package is installed.

main.cpp:3:10: fatal error: curl/curl.h: No such file or directory
    3 | #include <curl/curl.h>
      |          ^~~~~~~~~~~~~
compilation terminated.

Common causes

Development headers not installed

The runtime library may exist, but the -dev/-devel package that ships the headers (e.g. libcurl4-openssl-dev) is missing on the CI image.

Include directory not on the search path

The header is installed in a custom prefix that the compiler does not search by default, so -I is needed (or the CMake target’s include directories are incomplete).

How to fix it

Install the development package

Add the -dev/-devel package that provides the header.

# Debian/Ubuntu
apt-get update && apt-get install -y libcurl4-openssl-dev
# Fedora/RHEL
# dnf install -y libcurl-devel

Add the include directory

For a header in a custom prefix, add it to the compiler’s search path - or to the CMake target.

g++ -I/opt/curl/include main.cpp
# CMake equivalent
# target_include_directories(app PRIVATE /opt/curl/include)

How to prevent it

• Install all -dev/-devel packages your includes require in the runner image.
• Use find_package()/target_include_directories so include paths are explicit.
• Prefer pkg-config (pkg-config --cflags) over hard-coded -I paths.

Frequently asked questions

Related guides

References

• CMake documentation
• GitHub Actions documentation