TeX-Verzeichnisstruktur und Pfade

Eine TeX-Installation ist ein Haufen Zehntausender Dateien – Makros, Klassen, Schriftarten, Konfiguration. Warum findet das Schreiben der einzelnen Zeile \usepackage{amsmath} zuverlässig amsmath.sty irgendwo auf der Festplatte? Dahinter verbergen sich zwei Konventionen: ein Standard für den Speicherort von Dateien (TDS) und ein Mechanismus, um sie zu finden (kpathsea). Diese Seite zeichnet diese Karte.

Der TDS: ein Standardort für alles

Alles beginnt mit einem Verzeichnisbaum namens texmf-Baum – „texmf“ ist die Abkürzung für *TeX und Metafont*. Darunter sind die Dateien nach Art verzweigt: Makros und Klassen gehen unter tex/, alles, was mit Schriftarten zu tun hat, unter fonts/, bibliografische Daten unter bibtex/, Dokumentation (Handbücher) unter doc/, Skripte unter scripts/. Die Standardisierung dieses Layouts in allen Systemen ist die Aufgabe des TDS (TeX Directory Structure), der in den 1990er Jahren durch den TeX Users Group (TUG) definiert wurde.

Warum überhaupt einen Standard? TeX läuft auf macOS, Unix, Windows und mehr, und CTAN (der Comprehensive TeX Archive Network) sammelt einen riesigen Stapel Pakete. Wenn jede Site Dateien anders anordnen würde, würden sowohl die Leute, die Pakete versenden, als auch die Tools, die sie finden, jedes Mal ins Stolpern geraten. Sobald „Makros leben unter tex/“ behoben ist, kann der Speicherort jeder Datei allein aus den Regeln auf jedem OS und jeder Distribution abgeleitet werden. Portabilität ist genau das Problem, das der TDS löst.

Die Filialen haben ihre eigenen Regeln. tex/ wird nach Format, dann nach Paket aufgeteilt, was tex/<format>/<package>/ ergibt (wobei <format> latex, plain, generic, … ist). Der Standard article.cls befindet sich beispielsweise im folgenden Pfad – und das später eingeführte Tool kpsewhich meldet genau denselben Speicherort auf Ihrem eigenen Computer.

$ kpsewhich article.cls
/usr/local/texlive/2026/texmf-dist/tex/latex/base/article.cls

Schriftarten gehen eine Ebene feiner: fonts/<type>/<supplier>/<typeface>/. „<type>“ ist die Art von Datei – tfm für TeX-Schriftmetriken, vf für virtuelle Schriftarten sowie type1, opentype, truetype usw. Der <supplier> ist derjenige, der ihn bereitgestellt hat (public, adobe, ams, …) und <typeface> ist der Name der Schriftart (cm = Computer Modern). In der folgenden Tabelle sind die Zweige aufgeführt, denen Sie am häufigsten begegnen, und deren Inhalte.

Mehrere Bäume und welcher gewinnt

Ein texmf-Baum ist nicht eine Sache. TeX Live bündelt mehrere Bäume mit unterschiedlichen Rollen, die jeweils durch eine TEXMF…-Variable benannt werden. Warum sie trennen? Um drei Dinge auseinanderzuhalten: die Distribution (schreibgeschützt, wird bei jedem Update vollständig ersetzt), was Sie hinzugefügt haben (was nicht verschwinden darf) und automatisch generierte Arbeitsdaten. Mischen Sie sie, und eine Aktualisierung der Verteilung könnte Ihre eigenen Stile im Handumdrehen auslöschen.

Wenn eine Datei mit demselben Namen in mehreren Bäumen vorhanden ist, welche gewinnt? Das wird durch die Variable TEXMF entschieden, die einfach die Priorität der Suche der Reihe nach auflistet. Die Abfrage gibt ungefähr die folgende Reihenfolge zurück (ganz links gewinnt):

$ kpsewhich -var-value=TEXMF
{$TEXMFCONFIG,$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFSYSCONFIG,!!$TEXMFSYSVAR,!!$TEXMFDIST}

Lesen Sie es so: Zuerst Ihre eigene Konfiguration (TEXMFCONFIG) und Arbeitsdaten (TEXMFVAR), dann Ihr persönlicher Baum TEXMFHOME, dann der standortweite TEXMFLOCAL und schließlich die Systemkonfiguration, Arbeitsdaten und die Verteilung TEXMFDIST. Aufgrund dieser Reihenfolge führt das Ablegen Ihres eigenen mystyle.sty in TEXMFHOME dazu, dass es die Kopie der Distribution überschattet – kein Überfrachten, nur eine natürliche Rangfolge der persönlichen → Site → Distribution. (Das führende !! wird im nächsten Abschnitt erklärt.)

kpathsea: wie Dateien gefunden werden

Wer findet eigentlich eine Datei, selbst wenn das Layout festgelegt ist? Das ist kpathsea (kpse, *kpath search*) – die Pfadsuchbibliothek, die von TeX und seinen Begleittools gemeinsam genutzt wird. tex, pdflatex, dvipdfmx und der Rest führen keine eigenständige Suche durch; Sie alle fragen kpathsea: „Wo ist amsmath.sty?“

kpathsea drückt einen Suchpfad als Zeichenfolge mit Regeln aus. Drei Symbole sind wissenswert: $VAR erweitert eine Variable; ein abschließendes // bedeutet „alles darunter rekursiv durchsuchen“; und ein vorangestelltes !! bedeutet „Scannen Sie die Festplatte nicht direkt – konsultieren Sie nur die unten beschriebene Dateinamendatenbank.“ Der Pfad zum Auffinden von LaTeX-Quellen, TEXINPUTS, sieht tatsächlich so aus:

$ kpsewhich -var-value=TEXINPUTS
.:$TEXMF/tex/{latex,generic,}//

Lesen Sie es wie folgt: Schauen Sie zuerst in . (das aktuelle Verzeichnis) nach; Andernfalls durchlaufen Sie den tex/-Zweig jedes Texmf-Baums in der Reihenfolge latex → generic → alles andere. Dies führt zu dem intuitiven Verhalten, das Sie erwarten – eine Datei neben Ihrem Manuskript gewinnt, andernfalls greifen Sie auf die Verteilung zurück.

Aber wirklich jedes Mal Zehntausende Verzeichnisse zu scannen, wäre viel zu langsam. Daher verwendet kpathsea eine Dateinamendatenbank namens ls-R, die im Stammverzeichnis jedes Baums platziert wird – eine Textauflistung darüber, welche Datei sich in welchem ​​Verzeichnis befindet. Wenn Sie diesen Index konsultieren, anstatt die Festplatte zu durchsuchen, werden Suchvorgänge sofort durchgeführt. Das zuvor gesehene !! bedeutet „nur dem Index vertrauen (niemals die echte Festplatte berühren)“ und ist wie die Verteilung an Bäume gebunden, die sich selten ändern.

Die Kehrseite: Nach dem Hinzufügen einer Datei zu einem Baum findet TeX sie möglicherweise erst, wenn ls-R neu erstellt wird – insbesondere in den Systembäumen von !!. Der Befehl, der den Index neu generiert, ist mktexlsr, auch bekannt als texhash. Persönliche Bäume wie TEXMFHOME werden milder behandelt und müssen oft nicht neu erstellt werden, aber nachdem Sie etwas in TEXMFLOCAL eingefügt haben, besteht der sichere Schritt darin, die eine Zeile darunter auszuführen.

# Rebuild the ls-R filename databases after adding files to a tree
$ mktexlsr        # texhash is an exact alias

Wenn etwas schief geht, besteht der erste Schritt darin, Dateien und Variablen direkt mit kpsewhich abzufragen: „Welche Datei wird tatsächlich gelesen?“ und „Wozu erweitert sich diese Variable?“ werden sofort beantwortet, sodass Sie eine Fehlkonfiguration eingrenzen können. Der vollständige Satz der kpsewhich-Optionen und Verwaltungsbefehle wie tlmgr werden ausführlich auf einer separaten Seite behandelt.

PATH: der Weg zu den Befehlen

kpathsea findet die Dateien, die TeX liest, aber zuvor muss die Shell die ausführbare Datei selbst, pdflatex, finden. Das ist die Aufgabe von OS: Es durchsucht die in der Umgebungsvariablen PATH aufgeführten Verzeichnisse der Reihe nach. TeX Live speichert seine ausführbaren Dateien in einem einzigen Verzeichnis pro-OS und pro Architektur bin, und das Ablegen dieses Verzeichnisses auf PATH ist der letzte Schliff einer Installation.

Der Verzeichnisname bettet das Jahr und die Plattform ein: auf Linux /usr/local/texlive/2026/bin/x86_64-linux, auf macOS /usr/local/texlive/2026/bin/universal-darwin, auf Windows ...\bin\windows. Auf macOS stellt MacTeX einen jahresunabhängigen, stabilen Symlink bei /Library/TeX/texbin bereit, sodass für ein jährliches Upgrade keine Bearbeitung Ihres PATH erforderlich ist. Sie können sehen, worauf es derzeit hinweist:

$ which pdflatex
/Library/TeX/texbin/pdflatex
$ readlink /Library/TeX/texbin
Distributions/Programs/texbin

Wenn Sie jemals „pdflatex: command not found“ sehen, fehlt in neun von zehn Fällen einfach das Verzeichnis bin in PATH. Das OS-by-OS-Verfahren zum Festlegen und die Überprüfungen nach der Installation werden der Installationsseite überlassen.

texmf.cnf: woher die Einstellungen kommen

Woher kommen eigentlich alle bisherigen Variablen – TEXMF, TEXINPUTS, der Standort jedes Baums? Die Antwort ist eine Konfigurationsdatei namens texmf.cnf. Bevor etwas unternommen wird, liest kpathsea es, um die Betriebsparameter zu erfassen: die Suchpfade, wo sich jeder Baum befindet, Speichergrenzen und mehr. Die Masterkopie befindet sich unter der Distribution web2c/:

$ kpsewhich texmf.cnf
/usr/local/texlive/2026/texmf.cnf

Das Interessante daran: Es kann mehr als einen texmf.cnf geben. kpathsea liest texmf.cnf von mehreren Stellen entlang eines dedizierten Suchpfads (der Variable TEXMFCNF) der Reihe nach und nimmt die erste Definition, die es für eine bestimmte Variable findet (spätere Dateien überschreiben frühere nicht). Sie lassen also die große Standarddatei der Distribution unberührt und legen eine kleine Überschreibungsdatei an einem Speicherort mit höherer Priorität ab – ein Schichtschema, das nur Ihre Änderungen sicher hinzufügt. Durch Hinzufügen von -all werden die tatsächlich gestapelten Dateien angezeigt:

$ kpsewhich -all texmf.cnf
/usr/local/texlive/2026/texmf.cnf
/usr/local/texlive/2026/texmf-dist/web2c/texmf.cnf

Hier wird der obere texmf.cnf (die dünne Überschreibung von TeX Live) vor dem unteren texmf-dist/web2c/texmf.cnf (Hunderte Zeilen Standardwerte) gelesen. Wenn Sie einen Wert dauerhaft ändern möchten, besteht die Konvention nicht darin, die Datei der Distribution zu bearbeiten, sondern nur die benötigten Zeilen an einen Speicherort mit höherer Priorität wie TEXMFLOCAL/web2c/texmf.cnf zu schreiben. Wenn Sie das tun, überleben Ihre Einstellungen ein Distributions-Upgrade.

Zusammenfassend lässt sich sagen, wie TeX eine Datei findet: texmf.cnf korrigiert zunächst wo sich die Bäume befinden und wie die Suchpfade aussehen; dieser Reihenfolge folgend findet kpathsea das Ziel (normalerweise über den ls-R-Index); und PATH stellt den Einstiegspunkt zur ausführbaren Datei selbst bereit. Diese drei Schichten greifen ineinander, sodass eine einzelne Zeile von \usepackage{...} leise aufgelöst wird.

Wo können Sie Ihre eigenen Dateien ablegen?

Die wichtigste praktische Regel lautet: Bearbeiten Sie den Verteilungsbaum nicht. Wenn Sie ein thesisstyle.sty nur für die Abschlussarbeit oder ein laborweites labreport.cls in /usr/local/texlive/2026/texmf-dist platzieren, kann es durch ein Update oder eine Neuinstallation gelöscht werden. Legen Sie persönliche Dateien in TEXMFHOME und laborweite Dateien in TEXMFLOCAL ab und behalten Sie das TDS-Layout bei.

Im Gegensatz dazu können Dateien, die nur zu einem Einreichungspaket gehören – einer Konferenz myconf.cls oder einer Zeitschrift journal.sty – neben dem Manuskript liegen. TEXINPUTS überprüft zuerst das aktuelle Verzeichnis, daher wird TeX diese Kopie bevorzugen. Aus diesem Grund ist es auch gefährlich, generische Namen wie article.cls oder ein altes amsmath.sty neben dem Manuskript zu platzieren: Es überschattet die Verteilung und führt zu Fehlern, die nur auf anderen Computern auftreten.

# 個人用スタイルを TEXMFHOME に置く例
mkdir -p ~/texmf/tex/latex/thesisstyle
cp thesisstyle.sty ~/texmf/tex/latex/thesisstyle/

# TeX がどれを拾うか確認する
kpsewhich thesisstyle.sty

Sobald kpsewhich den erwarteten Pfad meldet, kann das Manuskript einfach \usepackage{thesisstyle} lauten. Wenn nichts gemeldet wird, überprüfen Sie der Reihe nach: ob sich die Datei unter tex/latex/<package>/ befindet, ob die Groß- und Kleinschreibung des Dateinamens übereinstimmt und ob mktexlsr für eine Systemstruktur ausgeführt wurde. Dies umrahmt den Fehler als „Wo habe ich es in der Suchkarte abgelegt?“ statt „TeX ist kaputt.“