Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

There are two different commands to incorporate another file into the source of some document, \input and \include. When should I use one or the other? What are the differences between them? Are there more things like them to be aware of?

share|improve this question
    
I didn't see mentioned anywhere that \include doesn't seem to recognize \label's in the included file. I changed to \input and the cross-references worked fine. –  Jeff Apr 4 at 3:26
add comment

4 Answers

up vote 288 down vote accepted

\input{filename} imports the commands from filename into the target file; it's equivalent to typing all the commands from filename right into the current file where the \input line is

\include{filename} essentially does a \clearpage before and after \input{filename}, together with some magic to switch to another .aux file, and omit the inclusion at all if you have an \includeonly without the filename in the argument. This is primarily useful when you have a big project on a slow computer; changing one of the include targets won't force you to regenerate the outputs of all the rest

\include gets you the speed bonus, but it also can't be nested, can't appear in the preamble, and forces page breaks around the included text.

share|improve this answer
33  
In terms of when to use them, \include is commonly used to put each chapter of a book or thesis into its own file. I keep a set of shortcut commands that I use in almost all of my documents in a .tex file in my path, and then \input it in the preamble of any document that needs to use them. –  Michael Underwood Jul 27 '10 at 6:44
3  
For completeness, note that \includeonly is the way that you select chapters to include, and so get the speed payoff. See also another question, which mentions this solution. –  Norman Gray Aug 28 '10 at 13:31
2  
@Michael, I add one more: see tex.stackexchange.com/questions/7010/… where \include cannot be used for path with spaces. –  xport Dec 13 '10 at 7:02
2  
From what I have observed right now \input is also a whole lot faster than \include. Splitting my thesis in 10 parts with \include just quadrupled my compile time, with \input I don't have this issue... –  fgysin Feb 21 '13 at 13:29
1  
The statement "`\input{filename}` ... is equivalent to typing all the commands from filename right into the current file" might be somewhat misleading, because this sounds as if it would mess up line numbers. It should be mentioned that this is not the case: If a (maybe even nested) \input contains a syntax error, LaTeX will correctly point to the line of the file you included, not the file which embeds the \input. –  bluenote10 Jan 16 at 14:47
add comment

Short answer:

\input is a more lower level macro which simply inputs the content of the given file like it was copy&pasted there manually. \include handles the file content as a logical unit of its own (like e.g. a chapter) and enables you to only include specific files using \includeonly{filename,filename2,...} to save times.


Long answer:

The \input{<filename>} macro makes LaTeX to process the content of the given file basically the same way as if it would be written at the same place as \input. The LaTeX version of \input only does some sanity checks and then uses the TeX \input primitive which got renamed to \@@input by LaTeX.

Mentionable properties of \input are:

  • You can use \input basically everywhere with any content.
    It is usable in the preamble, inside packages and in the document.
  • You can nest \input macros.
    You can use \input inside a file which is read using \input.
  • The only thing \input does is to input the file.
    You don't have to worry about any side effects, but don't get any extra features.

The \include{<filename>} macro is bigger and is supposed to be used with bigger amounts of content, like chapters, which people might like to compile on their own during the editing process.

\include does basically the following thing:

  • It uses \clearpage before and after the content of the file. This ensure that its content starts on a new page of its own and is not placed together with earlier or later text.
  • It opens a new .aux file for the given file.
    There will be a filename.aux file which contains all counter values, like page and chapter numbers etc., at the begin of the filename. This way the file can be compiled alone but still has the correct page and chapter etc. numbers. Such part aux files are read by the main aux file.
  • It then uses \input internally to read the file's content.

Mentionable properties of \include are:

  • It can't be used anywhere except in the document and only where a page break is allowed.
    Because of the \clearpage and the own .aux file \include doesn't work in the preamble, inside packages. Using it in restricted modes or math mode won't work properly, while \input is fine there.
  • You can't nest \include files.
    You can't use \include inside a file which is read by \include. This is by intention and is because to avoid issues with the .aux files. Otherwise three .aux files (main, parent \include, child \include) would be open at the same time which was deemed to complicated I guess.
    You can use \input inside an \include file and also \input an \include file.
  • Biggest benefit: You can use \includeonly{filename1,filename2,...} in the preamble to only include specific \include files.
    Because the state of the document (i.e. above mentioned counter values) was stored in an own .aux file all page and sectioning numbers will still be correct. This is very useful in the writing process of a large document because it allows you to only compile the chapter you currently write on while skipping the others. Also, if used persistently it can be used to create PDFs of sub-parts of your document, like only the front matter or everything but/only the appendix, etc.
    There is also the excludeonly package which provides an \excludeonly to exclude only certain files instead of including all other files.
share|improve this answer
2  
I've read several times that \include won't work in the preamble; @egreg in tex.stackexchange.com/questions/91167/why-use-sty-files even states never use \include for packages/definitions. However, due to limited knowledge when stating with LaTeX, I did exactly that, i.e. used \include in the preamble to load packages. And it worked flawlessly for numerous documents using TeTeX/TexLive2011, so I kept it till today (never change a running setup ;) The produced dvi file is binary identical when using \include or \input. But I keep in mind to try input if strange things happen. –  mpy Mar 2 '13 at 14:50
    
@mpy: Please don't tell other people to use \include in the preamble especially not to load packages! For these use \usepackage. \include causes a page break and does several things in the background, e.g. opens an .aux file for every file, etc. and should only be used for chapters or similar things. –  Martin Scharrer Mar 2 '13 at 15:13
1  
That was not my intention, I am only confused when I read \include won't work in preamble... Please feel free to delete my comment if you consider it as dangerous. –  mpy Mar 2 '13 at 15:18
add comment

From the LaTeX Wikibook :

When working on big documents, you might want to split the input file into several parts. LaTeX has three commands to insert a file into another when building the document.

The simplest is the \input command:

\input{filename}

\input inserts the contents of another file, named filename.tex; note that the .tex extension is omitted. For all practical purposes, \input is no more than a simple, automated cut-and-paste of the source code in filename.tex.

The other main inclusion command is \include:

\include{filename}

The \include command is different from \input in that it's the output that is added instead of the commands from the other files. Therefore a new page will be created at every \include command, which makes it appropriate to use it for large entities such as book chapters.

Very large documents (that usually include many files) take a very long time to compile, and most users find it convenient to test their last changes by including only the files they have been working on. One option is to hunt down all \include commands in the inclusion hierarchy and to comment them out:

%\include{filename1}

\include{filename2}

\include{filename3}

%\include{filename4}

In this case, the user wants to include only filename2.tex and filename3.tex. If the inclusion hierarchy is intricate, commenting can become error-prone: page numbering will change, and any cross references won't work. A better alternative is to retain the include calls and use the \includeonly command in the preamble:

\includeonly{filename2,filename3}

This way, only \include commands for the specified files will be executed, and inclusion will be handled in only one place. Note that there must be no spaces between the filenames and the commas.

Also, you cannot do \include in an \included document, so then just use \input.

share|improve this answer
add comment

\input effectively replaces the command with the contents of the input file. \input's can be nested. So, you can write:

\documentclass{article}

\begin{document}

AAA

\input{b}

AAA

\end{document}

where b.tex is:

BBB

\input{c}

BBB

and c.tex is:

CCC

to get output like:

AAA
BBB
CCC
BBB
AAA

include triggers a newpage both before and after the included material, rather as though you'd used an \input flanked by \clearpage commands. include also supports the \includeonly mechanism. So, the file:

\documentclass{article}

\includeonly{c}

\begin{document}

AAA

\include{b}

\include{c}

AAA 

\end{document}

with b.tex and c.tex as before, will produce output with AAA on page one, CCC on page two, and AAA on page 3.

The \include and \includeonly pair is very useful for working on long documents: you can \includeonly the file which you are editing, and compilation is much faster. If you do two runs on the full file before using \includeonly, page numbers and cross-references will remain valid for the quicker \includeonly compilation.

share|improve this answer
9  
+1 for \includeonly. However, IIRC the page numbers and cross-references will only remain valid for files \include'd before the current file. So if you are working on chapter four, and there's a reference to chapter 5 which is currently not looked at, references to chapter 5 (if you use just sequential numbering disregarding the chapters) may be wrong. –  Willie Wong Jul 27 '10 at 1:32
    
@Willie Wong is absolutely right. If you are working on Chapter 2 and add 5 pages, cross-references to pages of Chapter 3 will be off. Thanks for keeping things honest. –  vanden Jul 27 '10 at 1:35
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.