Paketkonflikte

! LaTeX Error: Option clash for package inputenc wird üblicherweise als „dasselbe Paket wurde zweimal mit unterschiedlichen Optionen geladen“ erklärt, und das trifft es nicht ganz. Was latex.ltx tatsächlich durchführt, ist ein Teilmengentest: Das zweite \usepackage geht durch, wenn jede angeforderte Option bereits unter den Optionen des ersten Ladens war, und kollidiert, sobald ein neuer Name auftaucht. Deshalb ist \usepackage[a,b]{X} gefolgt von \usepackage[a]{X} unbedenklich, während die umgekehrte Reihenfolge scheitert. Noch unangenehmer: Manche Pakete umgehen den Test vollständig, und xcolor ist das bekannteste Beispiel. Diese Seite behandelt, wie die Regel wirklich lautet, an welche Stelle \PassOptionsToPackage genau gehört, warum hyperref nahe am Ende geladen wird und welche Paketpaare sich auf TeX Live 2024 tatsächlich noch ausschließen.

Ausgelöst wird der Konflikt durch eine neue Option, nicht durch eine andere

Ein zweites \usepackage kollidiert in dem Moment, in dem es eine Option verlangt, die das erste Laden nicht hatte. Verlangt es dagegen eine Teilmenge der ersten Optionen – in beliebiger Reihenfolge, weniger davon oder gar keine –, passiert nichts. Der Grund steht in latex.ltx: \@onefilewithoptions@clashchk ruft \@if@ptions auf, dessen inneres \@if@pti@ns die angeforderten Optionen einzeln durchgeht und jede mit \in@ in der gespeicherten Liste sucht. Ein einziger Fehlschlag genügt für den zweiten Zweig, also \@latex@error{Option clash for …}. Sieben Kombinationen wurden auf TeX Live 2024 durchgespielt; die Tabelle unten zeigt das Ergebnis, aus dem die Regel unmittelbar folgt.

Die Fehlerzeile selbst ist knapp, doch die .log schreibt aus, mit welchen Optionen das Paket zuerst geladen wurde und welche nun verlangt werden. Diese vier Zeilen sind die eigentliche Diagnose – also lieber das Log öffnen, als auf das Terminal zu starren. Ebenfalls nützlich zu wissen: Die gemeldete Zeilennummer stimmt nicht. Da \usepackage am Ende ein optionales Datumsargument annimmt, muss es über die schließende Klammer hinweg nach einem [ schauen, und dieser Vorgriff reicht in die nächste Zeile. Deshalb wird ein Konflikt, den ein \usepackage in Zeile 3 auslöst, als l.4 \begin{document} gemeldet.

% terminal shows only the first line; the rest is in the .log
./oc1.tex:4: LaTeX Error: Option clash for package inputenc.
l.4 \begin
          {document}
The package inputenc has already been loaded with options:
  [utf8]
There has now been an attempt to load it with options
  [latin1]
Adding the global options:
  utf8,latin1
to your \documentclass declaration may fix this.

Warum xcolor nie kollidiert: drei Wege, den Test zu umgehen

\usepackage[dvipsnames]{xcolor} gefolgt von \usepackage[table]{xcolor} erzeugt auf TeX Live 2024 überhaupt keinen Fehler – nicht weil xcolor besonders nachsichtig wäre, sondern weil der Teilmengentest gar nicht aufgerufen wird. Für ein bereits geladenes Paket prüft \@onefilewithoptions in latex.ltx zuerst, ob ein Makro namens opt@handler@<Paket>.sty existiert. Existiert es nicht, geht es zu \@onefilewithoptions@clashchk, dem obigen Teilmengentest. Existiert es, übergibt der Kern die Sache vollständig und lässt diesen Handler die neu angeforderten Optionen verarbeiten. Und xcolor.sty auf TeX Live 2024 ist auf das neue Verfahren umgestellt: Es deklariert seine Optionen mit \DeclareKeys und verarbeitet sie mit \ProcessKeyOptions – und genau \ProcessKeyOptions registriert opt@[email protected]. Ein Blick mit \show liefert einen einzeiligen Rumpf: \ProcessKeyOptions [xcolor].

% no error on TeX Live 2024: xcolor uses \DeclareKeys + \ProcessKeyOptions
\usepackage[dvipsnames]{xcolor}
\usepackage[table]{xcolor}

% still an error: inputenc uses the classic \DeclareOption mechanism
\usepackage[utf8]{inputenc}
\usepackage[latin1]{inputenc}

% check for yourself which mechanism a package uses
\makeatletter
\expandafter\show\csname opt@[email protected]\endcsname
% -> \opt@[email protected]=\protected\long macro: ->\ProcessKeyOptions [xcolor].
\makeatother

Der Wechsel zu Schlüssel-Wert-Optionen ist der wohlerzogenste Umweg, doch es gibt zwei weitere. fontenc.sty setzt am Ende der eigenen Datei sowohl [email protected] als auch [email protected] auf \relax zurück – und da \@ifl@aded gerade ver@… abfragt, löscht fontenc die Tatsache, je geladen worden zu sein, sodass das nächste \usepackage[T2A]{fontenc} als Erstladen gilt. Der andere Fall ist caption, das in caption3.sty das kerneigene \@onefilewithoptions schlicht ersetzt: Wird ein Paket der caption-Familie erneut geladen, laufen die neuen Optionen durch das Äquivalent von \captionsetup, und danach wird das Paket mit leerer Optionsliste neu geladen. Der Kommentar des Autors direkt darüber berichtet, er habe das LaTeX-Team 2018 und noch einmal 2020 um eine ordentliche Schnittstelle gebeten und eine Absage erhalten, und er nennt seinen Ersatz einen „dirty hack“. Hinter einem Paket, das stillschweigend nicht kollidiert, steckt meist eine dieser drei Techniken.

Wohin \PassOptionsToPackage gehört: vor das erste Laden, sonst nirgends

\PassOptionsToPackage{opt}{X} bedeutet nur dann etwas, wenn es vor dem ersten Laden von X steht; der verlässliche Platz ist die erste Zeile der Datei, oberhalb von \documentclass. Der Befehl hängt lediglich opt an die Optionsliste [email protected] an – und dieser eine Handgriff bringt beide Wirkungen zugleich: opt wird X beim Laden übergeben, und ein späteres \usepackage[opt]{X} besteht nun den Teilmengentest. Die Option wirksam zu machen und den Konflikt zu beseitigen sind also nicht zwei Maßnahmen, sondern zwei Seiten derselben Zeile. Oberhalb von \documentclass darf sie stehen, weil \PassOptionsToPackage bereits auf Formatebene definiert ist und, anders als \usepackage, keine gelesene Klasse voraussetzt.

% correct: the very first line, above \documentclass
\PassOptionsToPackage{table}{xcolor}
\documentclass{article}
\usepackage{tikz}          % pulls xcolor in -- with table already attached
\usepackage[table]{xcolor} % no clash, and \rowcolor works

% WRONG: after xcolor is already loaded. No error is raised, and the
% option is silently never executed.
\documentclass{article}
\usepackage{tikz}
\PassOptionsToPackage{table}{xcolor}
\usepackage[table]{xcolor}

Der Befehl kann sehr leise scheitern. Steht \PassOptionsToPackage nach dem bereits erfolgten Laden von X, erscheint überhaupt kein Fehler – aber die Option wird nie ausgeführt. Mit einem instrumentierten Testpaket gemessen: vor dem Laden platziert, läuft der Code der Option nachweislich; danach platziert, verschwindet der Konflikt, und der Code bleibt unausgeführt. Zu glauben, das Problem sei gelöst, weil die Fehlermeldung fort ist, ist die gefährlichste Art, dieses Werkzeug zu benutzen. Eine zweite Falle steckt im Fehlertext selbst, der empfiehlt, die Optionen global an \documentclass zu geben. Wörtlich befolgt funktioniert das nicht: \documentclass[beta]{article} zu ergänzen und dabei \usepackage[alpha]{X} und \usepackage[beta]{X} stehen zu lassen, reproduziert den Konflikt unverändert. Erst wenn beide lokalen Optionslisten verschwinden – \documentclass[alpha,beta]{article} und zwei nackte \usepackage{X} –, geht es durch.

Herausfinden, wer das nie angeforderte Paket geladen hat

Ein \listfiles in der Präambel genügt, damit am Ende der .log jede tatsächlich geladene Datei steht; wer sie hereingeholt hat, verrät die Klammerverschachtelung im Log. Ein ( öffnet eine Datei, ein ) schließt sie – liegt also das ( von xcolor.sty innerhalb der Klammern von pgfcore.sty, dann hat pgf es hereingezogen. Gemessen: Ein nacktes article liest 3 Dateien, eine Zeile tikz bringt es auf 34, und xcolor ist darunter; hyperref allein steuert 30 bei. „Ich habe xcolor nie geschrieben und bekomme trotzdem einen Option clash“ beantwortet fast immer diese Liste. Für eine noch feinere Spur schreibt -recorder jede geöffnete Datei in eine .fls.

% the nesting says who pulled xcolor in: pgf did
(.../pgf/basiclayer/pgfcore.sty
(.../pgf/systemlayer/pgfsys.sty
...
)) (.../xcolor/xcolor.sty
...
)

% and with \listfiles, the summary table at the end of the .log
 *File List*
 article.cls    2023/05/17 v1.4n Standard LaTeX document class
  xcolor.sty    2022/06/12 v2.14 LaTeX color extensions (UK)
 ***********

Ladereihenfolge: warum hyperref nahe ans Ende gehört und was danach kommt

hyperref gehört nahe ans Ende, weil es sehr viele Mechanismen überschreibt – \ref, \cite, \caption, Inhaltsverzeichnis, Index – und ein Überschreiben muss die endgültige Definition treffen. Definiert später jemand dasselbe erneut, ist die Arbeit von hyperref schlicht getilgt. Die Regel lautet aber „nahe ans Ende“, nicht „zuletzt“. Pakete, die auf der Arbeit von hyperref aufbauen, müssen selbstverständlich danach kommen: bookmark, cleveref, hypcap und glossaries sind die üblichen. Besonders cleveref erkennt den Verstoß selbst und meldet einen Fehler, ein Irrtum fällt also sofort auf; die genauen Anforderungen behandelt die Seite zu undefinierten Verweisen.

Eines sollte klar gesagt werden. Ein großer Teil der Überlieferung „A muss vor B stehen“ bewirkt auf TeX Live 2024 gar nichts. Der Versuch, float mit hyperref, geometry mit hyperref, algorithm mit hyperref, bookmark mit hyperref und glossaries mit hyperref jeweils in beiden Reihenfolgen zu setzen, brachte in keinem Fall einen Fehler oder eine Warnung; die Pakete haben über Jahre Kompatibilitätscode angesammelt. Zu befolgen sind daher die Reihenfolgeregeln, die im Handbuch des jeweiligen Pakets stehen, und eine Präambel wegen einer Behauptung unklarer Herkunft umzusortieren, ist meist verlorene Zeit. Die Gewohnheit, hyperref nahe ans Ende zu setzen, bleibt trotzdem sinnvoll, denn sie folgt aus dem Wesen des Überschreibens und nicht aus Hörensagen.

Der Unterschied zwischen \usepackage und \RequirePackage

Innerhalb der Präambel sind die beiden buchstäblich dasselbe: Während der Verarbeitung von \documentclass führt latex.ltx ein \let\usepackage\RequirePackage aus, ab da handelt es sich um einen einzigen Befehl. Der Unterschied besteht nur vor \documentclass sowie in .sty- und .cls-Dateien. Dort bricht \usepackage mit ! LaTeX Error: \usepackage before \documentclass. ab – das \usepackage der Formatebene ist einzig dazu definiert, diese Diagnose auszugeben. Deshalb verwendet ein selbst geschriebenes Paket oder eine eigene Klasse \RequirePackage, und deshalb lässt sich in Kombination mit \PassOptionsToPackage eine Option oberhalb von \documentclass einschleusen. Möchte eine Klasse ihre eigenen Optionen unverändert an ein geladenes Paket weiterreichen, gibt es dafür \RequirePackageWithOptions.

% before \documentclass, only \RequirePackage works
\RequirePackage{fix-cm}
\PassOptionsToPackage{table}{xcolor}
\documentclass{article}

% inside your own mystyle.sty, likewise
\ProvidesPackage{mystyle}[2026/01/01 house style]
\RequirePackage{xcolor}
\RequirePackageWithOptions{geometry}  % forward this package's own options

Paare, die sich wirklich noch ausschließen, auf TeX Live 2024 überprüft

Jenseits der Optionen gibt es Paare, die nicht koexistieren können, weil sie dieselbe Maschinerie doppelt definieren. Es sind weniger, als die Überlieferung glauben macht, und das Symptom ist nicht immer ein Fehler beim Laden. Rundheraus ab lehnt biblatex zusammen mit natbib: Der Lauf hält bei ! Package biblatex Error: Incompatible package 'natbib'. – ging es nur um \citet und \citep, liefert \usepackage[natbib=true]{biblatex} genau das. Unangenehm sind die Paare, die still versagen: subfigure und subcaption gemeinsam zu laden erzeugt überhaupt keinen Fehler. Das Problem zeigt sich viel später als ! Missing number, treated as zero. in der Zeile mit \begin{subfigure}{0.4\textwidth}, weil \begin{subfigure} von dem alten Befehl \subfigure aus subfigure verschluckt und völlig anders gelesen wird.

Die Lehre aus dieser Liste lautet: einem „A und B sind inkompatibel“ nicht länger auf Hörensagen glauben, sondern ein fünfzeiliges Dokument bauen und nachsehen. Die Unverträglichkeit von caption mit subfigure war einst wirklich ein Fehler; heute ist sie zu einem Info herabgestuft. Umgekehrt ist subfigure mit subcaption der deutlichste Fall, in dem „es lud ohne Fehler, also passt es“ die gefährliche Schlussfolgerung ist. Das Symptom hat sich vom Fehler beim Laden zu einem viel späteren, scheinbar unzusammenhängenden Fehler verschoben – so steht es um Paketinkompatibilität auf TeX Live 2024, und genau deshalb zahlt sich die Gewohnheit aus, \listfiles zu setzen und die .log zu lesen.