The option-clash error: What and why
Many LaTeX packages allow for options to be specified when the package is loaded. For example, when you request that the xcolor package be loaded, you might specify the table option and the dvipsname option,1The table option forces the colortbl package to be loaded for coloring rows, columns, and/or cells of tables. The dvipsnames option makes available a particular set of predefined colors (in case you wanted, for example, to color text using the colors “Rhodamine” or “WildStrawberry”). See §2.1.2 (“Package options”) of Dr. Uwe Kern, “Extending LaTeX’s color facilities: The xcolor package,” v2.12, May 11, 2016. like so:2For more on the \usepackage command, see §3.2 Additional packages of the LaTeX2e unofficial reference manual.
\usepackage[table,dvipsnames]{xcolor}Your main document isn’t the only source of requests that packages be loaded: Any package you request might itself request that other packages be loaded—and with particular specified options.3When a package requests another package (as opposed to your main document requesting another package), the calling package uses the \RequirePackage command, e.g., \RequirePackage[table,dvipsnames]{xcolor}, instead of the \usepackage command. (For more on the \RequirePackage command, see §3.3.2 Class and package commands of the LaTeX2e unofficial reference manual.)
As a result of all this package-loading requesting, it’s possible that the same package will be requested multiple times—and with different options specified by different requests.
But here’s the catch: When a given package is requested more than once, only the first request is honored; all later-encountered requests to load that package are ignored,4See, e.g., The LaTeX Companion, 2nd edition, 2004, at (a) page 883 (“LaTeX loads a package only once because in many cases it is dangerous to execute the code of a package several times”) and (b) page 908 (“As LaTeX loads a package only once, the best solution is to specify all options on the first occasion”). along with whatever additional options those later requests specify.5You can think of each \usepackage and \RequirePackage command as a conditional request to load the specified package: “Dear LaTeX, if you haven’t already loaded this package, please do so now, using the options I specify here. If you have already loaded this package, ignore this command, including the options I’m specifying now.”,6“If a package is loaded, the option setting code in the package is already processed and gone.” (Heiko Oberdiek’s answer to “Applying options to already loaded package,” TeX Stack Exchange, July 15, 2013.)
Thus, multiple requests for the same package, when those requests specify different options, can cause you to encounter an Option clash for package error, like the error message at the top of this post.
An option-clash error occurs when:
- the same package is requested more than once (by a combination of
\usepackageand/or\RequirePackagecommands) and - a later-encountered request specifies a package option that was not specified by the first-encountered request.
I’m going to show you an easy, mechanical, highly reliable way to fix an option-clash error that won’t require you to know any details about what packages you’re loading, what order you’re loading them in, or what other packages those packages load.
Specifically, I’ll show you how to take two pieces of information from the error message and turn it into a \PassOptionsToPackage command to put at the beginning of your document. That will solve your option-clash error.
After that—because you may have heard some other prescriptions for this ailment—I’ll mention two other approaches that I do not recommend because (a) I want to discourage you from heeding inferior advice and (b) I want you to be assured that I did indeed take these alternatives into account before I made my recommendation here.
How to fix an option-clash error
Extract from the error message: (a) the package and (b) the options causing the clash
You know you have an option-clash package error because you received an error message that looks something like:
(That error message is what I see using Overleaf, a free, online, collaborative LaTeX-based writing and publishing service. If you see a shorter message—e.g., merely LaTeX Error: Option clash for package xcolor, it will probably be followed by the instruction to Type H <return> for immediate help. Doing so should retrieve and display the remainder of the error-message text.)
There are two key pieces of information that the error message will supply you with.
- The identity of the package with respect to which there’s a conflict. See the first line of the top-of-post error message:
LaTeX Error: Option clash for package xcolor
This line identifies
xcoloras the package with the clashing options.7In other words, thexcolorpackage is being requested more than once, and one of these later requests is specifying an option that wasn’t specified by the first request. The package identified in the error message is not the calling package; it’s the called package. Thus, it’s even possible that your main document doesn’t explicitly reference the identified package at all—if, for example, the calls for the problematic package were made by two packages you loaded, even though your document doesn’t directly call the problematic package. - The option(s) involved in the clash. In the above error message, look at the line:
Adding the global options: dvipsnames,table to your \documentclass declaration may fix this.
The only part of that line I want you to focus on is the list of options, viz., dvipsnames,table.8Don’t pay attention to the suggestion in the above error message about “[a]dding the global options… to your \documentclass declaration.” I explain below why that advice is not a good idea. (Note that this list is the union of the option(s) that “has already been loaded” and the option(s) that “there has now been an attempt to load” identified in the error message.9In other words, if X is the option(s) identified in the error message after “has already been loaded with options:” and Y is the option(s) identified in the error message after “there has now been an attempt to load it with options…,” then the list you want is X,Y.) This list of options may be as short as a single option, or it may have many options. You want the whole list, where each option is separated from its neighbors by a comma.
Use the package and option names to construct a \PassOptionsToPackage command and place it at the beginning of your document
Now we use (a) the name of the package with clashing options and (b) the list of options—that you identified in the previous section—to construct a \PassOptionsToPackage command, using the syntax:
\PassOptionsToPackage{}{}
where is the previously harvested list of options and is the previously identified package name.
For example, based on the error message at the top of the post, the corresponding \PassOptionsToPackage command would be:
\PassOptionsToPackage{dvipsnames,table}{xcolor}
The construction process for this example is depicted in this graphic:
Now take the \PassOptionsToPackage command you just constructed and put it at the very beginning of your main document. Although, normally, the first line of your document is probably a \documentclass command, you can even place the \PassOptionsToPackage command before that \documentclass command. The point is to make sure that the \PassOptionsToPackage command is seen before your document or any other package requests the package at issue here. Since it’s even conceivable that your document’s class itself requests that package, to be safe you can put the \PassOptionsToPackage command before the \documentclass command.
Rinse and repeat, as necessary, till your document is squeaky clean of option-clash errors
Now you’ve addressed your original option-clash error message by constructing a \PassOptionsToPackage command and placing it at the beginning of your document. So try to compile again.
Is there still an option-clash error?
- No? Congratulations! 🍾🏆💪🎉 You’ve solved your option-clash problems! 🛑
- Yes? Keep reading…
LaTeX will find only one pair of conflicting package-loading requests at a time and then stop. So you may have more option-clash errors to fix.
Go back to how to extract the relevant package and option names from the error message and harvest the new values to repeat the process.
If the new error message identifies the same problematic package (i.e., the package being called twice with conflicting options) but identifies additional conflicting options,10If the new error message is exactly the same as the prior error message—i.e., identifies the same package and exactly the same options—then that means that you made a mistake when you constructed, or placed, your \PassOptionsToPackage command. Go carefully through the process again, and check your spelling, to find your mistake. you can simply add the additional option names to your existing \PassOptionsToPackage command.11Or you can create a new \PassOptionsToPackage command. They are cumulative; i.e., you don’t need to include all the options for a particular package into a single \PassOptionsToPackage command.
If the new error message identifies a different problematic package, construct an additional \PassOptionsToPackage command for that package.
Keep repeating this process as many times as necessary to rid your document of option-clash errors.
How not to fix the option-clash error
Don’t try to fix it by changing the order of loading packages
You can sometimes fix an option-clash error by changing the order in which you load packages.
However, pursuing this kind of fix isn’t the best approach.
First, knowing how to reorder the package-loading requests would sometimes require that you have a lot of information about what other packages are loaded indirectly by the packages you load directly. That could take a lot of effort to discover and require some LaTeX sophistication.
Furthermore, even if you were willing to take that effort, you can’t always fix the error via changes in the order in which you load packages. For example, if one request for a package specifies only option x and another request for the same package specifies only option y, then—no matter which order you make these requests—the second request will specify an option that was not specified by the first request and that will generate an option-clash error.
For these reasons, I’d suggest: don’t try to solve your option-clash error by rearranging your package-loading requests. Instead, use the \PassOptionsToPackage method I’ve described above.
Ignore the suggestion to put options in your \documentclass command
You’ll note in the error message we’ve been considering that it suggests:
Adding the global options: dvipsnames,table to your \documentclass declaration may fix this.
This advice, although coming straight from a LaTeX error message, is erroneous. Ignore it.12Indeed, see David Carlisle’s answer to “Package options and \RequirePackage: order of commands and option conflicts?,” TeX Stack Exchange, July 25, 2012: “The help text for the option clash error suggests placing the clashing package in the global options on \documentclass but that in fact isn’t very good advice. (One might consider that a LATEX bug).”
First, it doesn’t reliably work.13Indeed, it doesn’t fix the problem in the example error message we’ve been looking at here.
Second, it’s not a good idea to make options global—meaning they will be seen and considered by every loaded package—without a better reason.14For example, see the comment by Enrico Gregorio (“egreg”) to Gonzalo Medina’s answer to “Option clash with xcolor and TikZ,” TeX Stack Exchange, April 11, 2012: “Every option passed to the class is ‘global,’ so that it’s tried with every loaded package. If the package knows it, it’s applied; otherwise it’s ignored.… [I]t’s not a good idea to indiscriminately pass package options as global options.” (Italics in original.) There are potentially unforeseen consequences, e.g., when two packages inadvertently use the same for different purposes.
Third, using the \PassOptionsToPackage method works so well that there’s no reason to do any more to fix your option-clash error.