What is the difference between #include <filename> and #include "filename"?

Question

In the C and C++ programming languages, what is the difference between using angle brackets and using quotes in an include statement, as follows?

1. #include <filename>
2. #include "filename"

Solution 1

In practice, the difference is in the location where the preprocessor searches for the included file.

For #include <filename> the preprocessor searches in an implementation dependent manner, normally in search directories pre-designated by the compiler/IDE. This method is normally used to include standard library header files.

For #include "filename" the preprocessor searches first in the same directory as the file containing the directive, and then follows the search path used for the #include <filename> form. This method is normally used to include programmer-defined header files.

A more complete description is available in the GCC documentation on search paths.

Solution 2

The only way to know is to read your implementation's documentation.

In the C standard, section 6.10.2, paragraphs 2 to 4 state:

• A preprocessing directive of the form

  #include <h-char-sequence> new-line
  

  searches a sequence of implementation-defined places for a header identified uniquely by the specified sequence between the < and > delimiters, and causes the replacement of that directive by the entire contents of the header. How the places are specified or the header identified is implementation-defined.

• A preprocessing directive of the form

  #include "q-char-sequence" new-line
  

  causes the replacement of that directive by the entire contents of the source file identified by the specified sequence between the " delimiters. The named source file is searched for in an implementation-defined manner. If this search is not supported, or if the search fails, the directive is reprocessed as if it read

  #include <h-char-sequence> new-line
  

  with the identical contained sequence (including > characters, if any) from the original directive.

• A preprocessing directive of the form

  #include pp-tokens new-line
  

  (that does not match one of the two previous forms) is permitted. The preprocessing tokens after include in the directive are processed just as in normal text. (Each identifier currently defined as a macro name is replaced by its replacement list of preprocessing tokens.) The directive resulting after all replacements shall match one of the two previous forms. The method by which a sequence of preprocessing tokens between a < and a > preprocessing token pair or a pair of " characters is combined into a single header name preprocessing token is implementation-defined.

Definitions:

• h-char: any member of the source character set except the new-line character and >

• q-char: any member of the source character set except the new-line character and "

Solution 3

The sequence of characters between < and > uniquely refer to a header, which isn't necessarily a file. Implementations are pretty much free to use the character sequence as they wish. (Mostly, however, just treat it as a file name and do a search in the include path, as the other posts state.)

If the #include "file" form is used, the implementation first looks for a file of the given name, if supported. If not (supported), or if the search fails, the implementation behaves as though the other (#include <file>) form was used.

Also, a third form exists and is used when the #include directive doesn't match either of the forms above. In this form, some basic preprocessing (such as macro expansion) is done on the "operands" of the #include directive, and the result is expected to match one of the two other forms.

Solution 4

Some good answers here make references to the C standard but forgot the POSIX standard, especially the specific behavior of the c99 (e.g. C compiler) command.

According to The Open Group Base Specifications Issue 7,

-I directory

Change the algorithm for searching for headers whose names are not absolute pathnames to look in the directory named by the directory pathname before looking in the usual places. Thus, headers whose names are enclosed in double-quotes ( "" ) shall be searched for first in the directory of the file with the #include line, then in directories named in -I options, and last in the usual places. For headers whose names are enclosed in angle brackets ( "<>" ), the header shall be searched for only in directories named in -I options and then in the usual places. Directories named in -I options shall be searched in the order specified. Implementations shall support at least ten instances of this option in a single c99 command invocation.

So, in a POSIX compliant environment, with a POSIX compliant C compiler, #include "file.h" is likely going to search for ./file.h first, where . is the directory where is the file with the #include statement, while #include <file.h>, is likely going to search for /usr/include/file.h first, where /usr/include is your system defined usual places for headers (it's seems not defined by POSIX).

Solution 5

The exact behavior of the preprocessor varies between compilers. The following answer applies for GCC and several other compilers.

#include <file.h> tells the compiler to search for the header in its "includes" directory, e.g. for MinGW the compiler would search for file.h in C:\MinGW\include\ or wherever your compiler is installed.

#include "file" tells the compiler to search the current directory (i.e. the directory in which the source file resides) for file.

You can use the -I flag for GCC to tell it that, when it encounters an include with angled brackets, it should also search for headers in the directory after -I. GCC will treat the directory after the flag as if it were the includes directory.

For instance, if you have a file called myheader.h in your own directory, you could say #include <myheader.h> if you called GCC with the flag -I . (indicating that it should search for includes in the current directory.)

Without the -I flag, you will have to use #include "myheader.h" to include the file, or move myheader.h to the include directory of your compiler.

View more solutions

Comments

[Richard Corden]

The statement: "the preprocessor searches in the same directory..." may be true in practice but the standard states that the named source file is "searched for in an implementation-defined manner". See answer from piCookie.

[Dan Moulding]

+1, this is probably the most concise and correct answer here. According to the standard (which piCookie quotes from in his answer), the only real difference is "header" versus "source file". The search mechanism is implementation-defined either way. Using double quotes means that you intend to include a "source file", while angle brackets mean you intend to include a "header" which, as you say, may not be a file at all.

[Nav]

I know I'm asking this a long time after you posted the answer, but @aib, what do you mean by "uniquely refer to a header, which isn't necessarily a file"? Even a header-files are files!

[aib]

See Dan Moulding's comment to quest49's answer; standard headers don't have to be in file form, they can be built-in.

[Maxim Egorushkin]

I've been reading this "standard headers don't have to be in file form" for a decade. Care to provide a real-world example?

[Loghorn]

However, using angle brackets or quotes doesn't affect the way the files are included, it is exactly the same: the preprocessor essentally creates a large source file by copy'n'pasting the code from include files to original source file, before giving it to the compiler (preprocessor does other thing, like #define sustitution, #if evaluation, etc. but the #include processing is that easy)

[the_mandrill]

What about conflicts? eg say I have zlib.h in my 'user' search paths, and a different version exists in the system search path, then does #include <zlib.h> include the system version and #include "zlib.h" include my own?

[the_mandrill]

Aha, answered my own question: stackoverflow.com/questions/21593/…

[Keith Thompson]

No, #include "mypath/myfile" is not equivalent to #include "./mypath/myfile". As piCookie's answer says, double quotes tell the compiler to search in an implementation-defined manner -- which includes searching in the places specified for #include <...>. (Actually, it probably is equivalent, but only because, for example, /usr/include/mypath/myfile can be referred to as /usr/include/./mypath/myfile -- at least on Unix-like systems.)

[Gabriel Southern]

"... the preprocessor searches in the same directory as the file being compiled for the file to be included." This statement is not completely correct. I was interested in this question because I was curious what the actual answer is, but I know this is not true because at least with gcc when you specify an additional include path with -I that will search for files specified with #include "filename.h"

[Maxim Egorushkin]

Not sure why people disagree.

[Admin]

I suspect that's because most people compile only the files in their CWD. If you're in directory foo, and you're compiling foo/unittest/bar.c, and it includes bar.h, then "bar.h" works and <bar.h> does not.

[Alexander Malakhov]

Relevant: implementation in g++ and in visual c++

[Dan Moulding]

@Maxim Yegorushkin: I can't think of any existing real-world examples either; however, no complete C11 compiler can exist for MS-DOS unless headers don't have to be files. This is because some of the C11 header names are not compatible with the "8.3" MS-DOS file name limitation.

[onmyway133]

@piCookie both <filename> and "filename" search for implementation-defined places. So what is the difference ?

[piCookie]

@entropy: In a forum like this, it is not possible to answer your question. An answer that would be correct for one particular compiler could be entirely wrong for another. Each particular implementation / compiler should be obligated to spell out the difference, and that is the only reliable way to know. Several other answers have given examples, and perhaps your implementation is mentioned in one of those.

[Stefan]

@piCookie but you could say that angle brackets are inspecting the INCLUDE_PATH, where "" doesn't. so angle brackets are introducing a search path but aren't cwd at all. actually there is no difference, if you reduce it to the point, that <> only searches on the standard include path.

[piCookie]

@Stefan, I'm just quoting the standard which does not say anything about INCLUDE_PATH. Your implementation may do that, and mine may not. The original question was generically C and not specifically gcc (which I don't think uses INCLUDE_PATH) or Microsoft C (which I think does) or any other, so it can not be answered generically but instead each implementation's documentation must be referenced.

[Stefan]

@piCookie no. INCLUDE_PATH was more meant to be as a variable containing the standard paths for the compiler, not a vendor specific implementation detail.

[gnasher729]

Headers are not necessarily files. If you write #include <stdlib.h>, the header could be directly built into the compiler.

[Stefan Steiger]

@Keith Thompson: That's right, I was thinking of my Linux box. Evidently it could be different. Though in practice, Windows as non-Posix operating system also does interprete / as path separator, and ./ also exists.

[Protongun]

the -L dirpath option then adds dirpath to the defaultincludepaths, as opposed to giving another meaning to the . (as referred to above). This has the expected consequence that both #include "..." and #include <...> search in dirpath

[vargonian]

As with all of these situations, concrete examples (especially of common scenarios) are greatly useful and equally appreciated. Needlessly obtuse generic answers don't have as much practical use.

[Rudy Velthuis]

I don't exactly know how this is in C, bit if I read the standard quotation above, the sequence between < and > does not necessarily have to be a file name. Anything that uniquely defines a header will do. In C++, this means that <algorithm> does not necessarily map to a file called "algorithm" or "algorithm.h". How this file is actually named, or if the header is even a file in the file system is implementation defined. But the q-char-sequence in the second version does indeed contain a real file name.

[cloudcell]

@onmyway133 the standard allows for two alternative search mechanisms. If an alternative search mechanism (for include "") is not implemented, include "" functions as include <>. However, this quote from the standards definitely should have a summary -- no one has to waste time figuring out what it implies.

[osgx]

What is exact source of the text? Is it from normative part of IEEE Std 1003.1, 2013?

[anatolyg]

"Here's how the C standard can be verbose and not answer your question"

[osvein]

@Maxim people disagree because the behaviour you describe is not standard C.

[supercat]

@DanMoulding: The MS-DOS based compilers I've seen would almost invariably interpret #include "thisIsAVeryLongName.and.I.Love.Dots.h" as a request to read a file THISISAV.AND`; one would give a warning that the name in the directive didn't match the file; the rest I've seen would simply ignore that. Would any of the headers required for C11 not work under such a model, e.g. because two distinct names have a shared 8-letter prefix?

[Jacksonkr]

"The only way to know is to read your implementation's documentation." Or by asking someone on Stack Overflow. I appreciate that you went for the "teaching moment" but I'm afraid that attitude is quickly becoming outdated.

[Kyle Strand]

This is mostly just the same text as piCookie's answer from seven years earlier.

[Kyle Strand]

Thank you for acknowledging that both the standard(s) and typical implementation conventions are both relevant here, rather than simply stating that it's unknowable because it's not specified by the standard.

[skyking]

@KyleStrand That's because the same text is a quote of the relevant section in the standard - that text should be identical. The actual answer is not the same text and is somewhat different - while I also recognize that it will be written in the documentation for the implementation I also note that there's also a traditional way these are interpreted (that most or all compilers I used respects).

[plugwash]

IMO this is the best answer here, because it covers both what the standard says and what most compilers actually do.

[Maxim Egorushkin]

"both <filename> and "filename" search for implementation-defined places". How is this answer practically useful?

[Maxim Egorushkin]

@Spookbuster Right, the standard says both <filename> and "filename" search for implementation-defined places.

[Carlo Wood]

I think this answer is incorrect, since it implies that headers included with double quotes are always looked for in the current working directory. The search mechanism is way more detailed; this answer is incomplete. I'm not adding this comment to complain or whine, but because the system asks me to add a comment to explain why I voted this answer down.

[akhan]

@MaximEgorushkin see Alexander Malakhov's comment for links that describe the implementation for gcc and visual C++. There should be similar documentation for any other commercial compiler. IMO, Alexander's comment should be part of the answer.

[Dave Voyles]

People come here to have things explained to them in a manner which they can understand. Simply pointing to cryptic documentation is not helpful. That poor documentation is exactly why so many of us are at this exact question.

[Jonathan Leffler]

@osgx: that wording (or something extremely similar) is found in the POSIX specification for c99 — which is the POSIX name for the C compiler. (The POSIX 2008 standard could hardly refer to C11; the 2013 update to POSIX 2008 did not change the C standard that it referred to.)

[Adrian McCarthy]

@MaximEgorushkin: The VAX/VMS C compiler kept all the C runtime library headers in a single textual library file (similar to a unix archive), and used the string between the < and > as the key to index into the library.

[osvein]

@DaveVoyles-MSFT this is the only correct answer, because the question didn't specify which implementation, just "the C and C++ programming languages". How some implementations handle #include has already been pointed out in the comments, which is where they belong because they wouldn't really answer the question.

[0kcats]

Those who don't like the answer, please, give one practical example, where it is wrong.

[Wolf]

a header, which isn't necessarily a file -- reminds me of URLs (mostly files in the beginning and these days everything you can think of)

[John P]

Sure enough, I recently mixed these syntaxes when including headers from 'the same' library and ended up with redefinition errors. If I understand correctly, #include <...> used the package installed on the system and #include "..." used the nearby repository version. I might have those backwards. Either way, the include guard in the packaged header is prefixed with an underscore. (It could be a convention for packages or maybe a way to deliberately prevent mixing the two, although version qualifiers would make more sense to me.)

[Daniel Langr]

Which new information adds this answer to the other ones?

[Suma]

If the answer is to be of any use, it should mention the intended purpose and common use of those directives, not only quote the standard, which tells how things are defined, but does not tell why. The answer should include the fact <> is used to include standard library headers, while "" is used to include project local includes.

[SteamyThePunk]

The purpose of quoting the standard is to show that there is no answer provided by the standard, as the difference, if any, between these two forms is entirely up to the implementation, Which is why quoting the standard was predicated by suggesting you read your implementation's relevant documentation because OP didn't state what their implementation was. To put it bluntly: There is no standard answer, so you MUST consult your implementation's relevant documentation to find out for your particular case.

[IInspectable]

After a perfect answer had been available for years, why submit one, that's just blatantly wrong? Even though common, the #include directive isn't strictly related to files at all.

[Kamran Poladov]

Why do some windows users #include pch.h file in quotes? It's not somewhat "programmers-defined" file

[mckenzm]

In effect it allows the included content to be "hotfixed" during compilation to "override" the normal include path. It prevents mangling someone else's original (from a github library, say) source. This is very common for Arduino libs and even cores.

[Behrooz Karjoo]

@IInspectable please explain why it's not related to files at all.

[C.J.]

It has nothing to do with pre-defined header files at all. It has to do with locations to search for.

[Jonathan Leffler]

If you decide to answer an older question that has well established and correct answers, adding a new answer late in the day may not get you any credit. If you have some distinctive new information, or you're convinced the other answers are all wrong, by all means add a new answer, but 'yet another answer' giving the same basic information a long time after the question was asked usually won't earn you much credit.

[Jonathan Leffler]

If you decide to answer an older question that has well established and correct answers, adding a new answer late in the day may not get you any credit. If you have some distinctive new information, or you're convinced the other answers are all wrong, by all means add a new answer, but 'yet another answer' giving the same basic information a long time after the question was asked usually won't earn you much credit.

[personal_cloud]

@Jonathan Leffler Can you point me to the "well established" answer that you feel is as concise and accurate as Darshan's answer?

[Jonathan Leffler]

The description of the #include "header.h" form is not accurate, @personal_cloud. I consider the answer by piCookie and Yann Droneaud to be most relevant as they identify where their information comes from. I don't find the top-voted answer to be entirely satisfactory, either.

[Neonit]

Why is this answer shown on top, while two answers further down there is a 650+ votes one? This answer confused me, because it doesn't match the behavior observed by me. This might be, because the last sentence is broken due to not escaping angle brackets. I'm not sure what it is supposed to mean.

[Pryftan]

This was my first thought too. The manpage for gcc includes this as do others. There's also a similar thing for libraries - -L.

[Pryftan]

Yes - there are several different ways of generating dependencies. That's one of them but it's not the only one.

[paxdiablo]

"One practical example where it's wrong" is irrelevant. Standards exist for a reason. The guideline (in the standard) is to use <> for headers included with the implementation, "" for everything else. But it's made clear that this is a guideline only, the search paths for both cases are implementation defined other than the fact "" will fall back to <> if it can't be found.

[Jack M]

What is a "quote directory"?

[Eljay]

@JackM • there are 3 locations: the #include-ing file's current directory, the quote directories (the paths to check for the #include "foo.h" style includes), and the system directories (the paths to check for the #include <bar.h> style includes).

[littleO]

What does "system" mean in the phrase "system header file"? I find that computer scientists throw around this word "system" a lot and I often can't tell if it means "operating system", "computer system", or something else.

[supercat]

On a related note, the Standard says nothing about what characters an implementation must accept in filenames, nor what lengths of filenames an implementation must accept. A conforming implementation could run on a file system where filenames were limited to six alphanumeric characters, and reject any directives of the form #include "fname" where the file name contained periods, but a conforming implementation must accept e.g. ` #include <float.h>` without regard for whether float.h would be a valid file name.

[IInspectable]

@beh This answer does a perfect job doing just that.

[Andrew]

@Suma - you have to remember that when C was first standardised, it was already 15+ years old, and different implementations did things differently... these differences were documented as "implementation defined"

[Nathan Reed]

This is incorrect. While compilers do treat system headers differently, that behavior isn't triggered by using angle brackets in the #include, but by the headers being in specific system directories. See gcc and Microsoft docs on the subject.

[david]

@Nathan-Reed Read your sources again, try to understand what they mean, and delete your comment.

[Nathan Reed]

I suggest you reread the sources. Again, using angle brackets in the #include does not trigger the system header behavior, as your answer claims. The only exception is with VS with the /external:anglebrackets flag, which is non-default.

[Admin]

This is the best answer. This topic can be discussed ad infinitum for years and decades, but the clear compiler trend is that <> is for system headers and " " is for local directory and project headers. I use <> for system headers and " " for everything else. That way it's clear in code whether a header is a system header. Plus, this way, if you move local project headers to different directory as you change code, you don't need to change " " to <> and vice versa. (PS: This is also the ReSharper C++ methodology with includes headers automatically for you).

[Bill Gale]

I agree this is the best answer. For clarification, to me a system file is anything you did not write, and are referencing, of course your compiler includes, but beyond that any other installed packages. And a program file you wrote. Using Google protobufs, a system file would be <google/protobuf/type_pb.h>, and a program file would be your protobuf "mydir/my_pb.h".

[d512]

Crazy that so few people (including myself) understand something so basic to developing in C/C++. The tyranny of poorly documented conventions.

[paxdiablo]

I also agree this is a very good answer but only if your world is limited to using gcc and similarly-behaving environments :-) The question asked about C, which is much wider in scope than gcc. This answer would be much better if it mentioned that limitation. As it stands now, it could be read as implying these rules are sacrosanct across all implementations.

[PRouleau]

The question is more general than your answer, which only addresses one aspect of C++ and ignores C. And I agree with C Jonhson. The C++ does support extension-less headers (which are a real pain for some tools, BTW) but it can also be used to identify a file which will be searched with an implementation-specific way as described in the other answers.