When can you omit the file extension in an #include directive?

I'm playing around with gmock and noticed it contains this line:

#include <tuple>

I would have expected tuple.h.

When is it okay to exclude the extension, and does it give the directive a different meaning?


  • The C++ standard headers do not have a ".h" suffix. I believe the reason is that there were many, different pre-standard implementations that the standard would break. So instead of requiring that vendors change their existing "iostream.h" (for example) header to be standards compliant (which would break their existing user's code), the standards committee decided that they'd drop the suffix (which, I believe no then existing implementation had already done).

    That way, existing non-standard programs would continue to work using the vendor's non-standard libraries. When the user wanted to make their programs standards-compliant, one of the steps they would take is to change the "#include" directive to drop the ".h" suffix.


    #include <iostream>     // include the standard library version
    #include <iostream.h>   // include a vendor specific version (which by 
                            //      now might well be the same)

    As other answers have mentioned, writers of non-standard libraries may choose either naming convention, but I'd think they would want to continue using ".h" or ".hpp" (as Boost has done) for a couple of reasons:

    1. If and when the library gets standardized, the standard version won't automatically override the previous, non-standard one (causing broken user code in all likelihood).
    2. It seems to be a convention (more or less) that headers without a suffix are standard libraries, and those with a suffix (other than the C compatibility headers) are non-standard.

    Note that a similar problem happened when the committee went to add hash maps to the STL - they found that there are already many (different) hash_map implementations that exist, so instead of coming up with a standard one that breaks a lot of stuff out there today, they call the standard implementation "unordered_map". Namespaces were supposed to help prevent this type of jumping through hoops, but it didn't seem to work well enough (or be used well enough) to allow them to use the more natural name without breaking a lot of code.

    Note that for the 'C' headers, C++ allows you to include either a <cxxxxxx> or <xxxxxx.h> variant. The ones that start with 'c' and have no ".h" suffix put their declarations in the std namespace (and possibly also in the global namespace); the ones with the ".h" suffix put the names in the global namespace (and possibly also in the std namespace).