Skip to content

The xr package is used for cross-referencing across multiple independent documents. For example, you would use the xr package if you had two separate files in a project, File1.tex and File2.tex, and you would like to have a reference in File1.tex to something labelled in File2.tex, without including File2.tex in File1.tex.

To do this in Overleaf, there are some extra steps required which are outlined below.

  Open an example in Overleaf

Loading the xr package

The first thing required is to simply load the xr package in the main file you are working on. In this case, this simply means we include


in the preamble of File1.tex.

If you're using the hyperref package in your main file (i.e. File1.tex), then load xr-hyper instead of xr in File1.tex before hyperref. You'll also need to load the hyperref package in the external document (i.e. File2.tex).

Add some additional code to the preamble of File1.tex

We now need to add some additional `helper' code to the preamble of File1.tex as shown below:

% In your preamble

\newcommand*{\addFileDependency}[1]{% argument=file name and extension
  \IfFileExists{#1}{}{\typeout{No file #1.}}


This simply creates a new command of \myexternaldocument{...} which allows you to specify the document whose labels you would like to reference.

Specifying the external document

The next step is to specify the external document whose labels you would like to reference. This is the only part of the code you will have to change yourself depending on the name of the file.

% In your preamble


Here, File2 can be replaced by whatever file you would like to reference the labels of.

Creating the latexmkrc file

The next step is to create a latexmkrc file as shown below:

  • In your project editor window, click on `Add file' on the top of the project sidebar.
  • Select `Blank file', and name the file latexmkrc.
  • Make sure that the latexmkrc file is in the top (root) level of the project's files area. That is, not inside any folders in the file tree.
  • Add the following code to the file latexmkrc:

add_cus_dep( 'tex', 'aux', 0, 'makeexternaldocument' );

sub makeexternaldocument {
    if (!($root_filename eq $_[0]))
        system( "latexmk -cd -pdf \"$_[0]\"" );

This compiles the external document File2 with the PDFLaTeX engine, and the auxiliary files produced are saved in the cache to be accessed and referenced as File1 is compiled. If your external file needs to be compiled with a different engine, the appropriate command should be commented out from the following (by removing the preceeding #; here, PDFLaTeX is used again):

add_cus_dep( 'tex', 'aux', 0, 'makeexternaldocument' );

sub makeexternaldocument {
    if (!($root_filename eq $_[0]))
        # FOR PDFLATEX
        system( "latexmk -cd -pdf \"$_[0]\"" );

        # system( "latexmk -cd \"$_[0]\"" );

        # FOR XELATEX
        # system( "latexmk -cd -xelatex \"$_[0]\"" );
        # FOR LUALATEX
        # system( "latexmk -cd -lualatex \"$_[0]\"" );

Final Project

Once all the steps above have been completed, you are ready to start referencing across different documents. This is done in the exact same way as normal. If you have a something in File2.tex labelled with \label{file2:introduction}, then you can simply reference this in File1.tex by writing \ref{file2:introduction}.

  Open an example in Overleaf

% In File1.tex

We can reference the image \ref{picture} of File2.tex.

% In File2.tex


A note about syntax errors

When Overleaf compiles your project, our default settings attempt to produce a PDF even if your LaTeX source code contains syntax errors. However, because the external document is processed with different settings (as specified in the latexmkrc file), if the external document contains LaTeX syntax errors, it will not properly record all the cross-references in many cases. In this case (as always) we recommend correcting LaTeX syntax errors as soon as they come up, rather than letting them build up. Even if a PDF is produced, it may not contain what you expect. Letting many errors build up can also result in hard-to-debug problems in the future.

Source: TeX.SX: latexmk with external references.

Overleaf guides

LaTeX Basics


Figures and tables

References and Citations


Document structure





Field specific

Class files

Advanced TeX/LaTeX