Wie gut eine LaTeX-Installation altert, entscheidet nicht das Auswendiglernen der Optionsliste von tlmgr, sondern das Wissen, wohin eine Datei gehört. Wird der Suchpfad TEXMF ausgegeben, steht vor manchen Bäumen ein !! und vor anderen nicht. Es bedeutet „die Platte nicht durchsuchen, nur die ls-R-Datenbank befragen“, und diese zwei Zeichen entscheiden, ob eine von Hand abgelegte Datei sofort gefunden wird oder unsichtbar bleibt, bis mktexlsr läuft. Diese Seite behandelt das Hinzufügen und Aktualisieren von Paketen mit tlmgr, die Arbeitsteilung zwischen dem persönlichen Baum TEXMFHOME und dem Systembaum TEXMFLOCAL, die Installation von Hand aus CTAN sowie die Verwaltung der Font-Maps (updmap) – mit den Werten einer real vermessenen TeX-Live-2024-Installation.
Ein Paket hinzufügen: wie tlmgr install arbeitet
Der Standardweg, ein LaTeX-Paket hinzuzufügen, ist eine einzige Zeile: tlmgr install <Name>; die Abhängigkeiten kommen standardmäßig mit. Man kann Pakete einzeln nennen oder eine ganze Sammlung wie collection-fontsrecommended hereinholen. Die Installation in einen systemweiten Baum verlangt Administratorrechte (unter Unix sudo tlmgr install …, unter Windows eine erhöhte Shell). --no-depends unterdrückt die Abhängigkeiten, --reinstall überschreibt beschädigte Dateien.
# Install a package; dependencies come along by default
tlmgr install siunitx
tlmgr install collection-fontsrecommended
# Skip dependencies, or overwrite a broken install
tlmgr install --no-depends siunitx
tlmgr install --reinstall siunitx
# A system-wide tree needs admin rights
sudo tlmgr install siunitxWichtiger ist in der Praxis der Weg von der Fehlermeldung zum Paketnamen. Erscheint etwa LaTeX Error: File siunitx.sty not found, ist es der denkbar schlechteste Zug, ein per Suchmaschine gefundenes .sty in den Manuskriptordner zu legen. Erst Dateiname und Paketname trennen: Die Datei heißt siunitx.sty, das Paket siunitx – meist gleich, oft aber nicht: tikz.sty steckt im Paket pgf. tlmgr search --global --file beantwortet die Frage „welches Paket liefert diese Datei“ und schlägt damit die Brücke. Ist der Name nur halb erinnert, hilft tlmgr search --global <Wort>; wer wissen will, was ein Paket ist, bekommt mit tlmgr info <Name> Beschreibung, Lizenz, Größe und Dateiliste.
# From "File siunitx.sty not found" to an installed package
kpsewhich siunitx.sty # is it already here?
tlmgr search --global --file siunitx.sty # which package ships it?
tlmgr install siunitx # install it properly
# Half-remembered name, or curious about a package
tlmgr search --global siunit
tlmgr info siunitxEin leicht zu übersehendes Verhalten: Weder tlmgr install noch tlmgr remove erneuert die symbolischen Links in Systemverzeichnissen wie /usr/local/bin. Zeigt der PATH direkt auf das bin-Verzeichnis von TeX Live, spielt das nie eine Rolle; wer aber mit tlmgr path add Links für Programme, man- und info-Seiten anlegt, muss nach der Installation eines Pakets mit neuem Programm selbst tlmgr path add erneut ausführen (und nach dem Entfernen tlmgr path remove). Wem die Kommandozeile nicht liegt: TeX Live liefert zusätzlich tlshell, eine Tcl/Tk-Oberfläche, die suchen, installieren, entfernen, sammelweise aktualisieren und Repositories umschalten kann – und das Protokoll der ausgeführten Befehle zeigt, was den Einstieg in tlmgr erleichtert.
Aktualisieren: --self und --all gehören zusammen
Der Standardschritt ist eine Zeile: tlmgr update --self --all – --self bringt tlmgr selbst, also die Infrastruktur, auf den Stand, --all alles Übrige. Die Reihenfolge ist keine Geschmacksfrage. Das Handbuch zu tlmgr hält zu --all fest, dass alle installierten Pakete außer tlmgr selbst aktualisiert werden und dass bei vorliegenden Aktualisierungen für tlmgr ein Fehler ausgegeben wird, sofern nicht zusätzlich --force oder --self angegeben ist. Ein veraltetes tlmgr bleibt also stehen und besteht darauf, sich zuerst zu ersetzen. Mit beiden Schaltern tut es genau das: Es erneuert sich selbst und setzt bei Erfolg unter der neuen Fassung mit dem Rest fort.
# The standard move: infrastructure first, then everything else
tlmgr update --self --all
# See what would change before committing to it
tlmgr update --list
# Update one package only
tlmgr update siunitxEs lohnt zu wissen, was dieses Update sonst noch tut. Pakete, die serverseitig aus einer Sammlung entfernt wurden, werden automatisch deinstalliert, neu zu einer vorhandenen Sammlung hinzugekommene Pakete automatisch installiert; --list zeigt beides vorab. Woher geholt wird, bestimmt die Einstellung Repository, standardmäßig die automatische Spiegelverteilung von CTAN. Bei langsamer Leitung oder wenn ein bestimmter Spiegel festgelegt werden soll, dauerhaft mit tlmgr option repository umschalten; für einen einzelnen Lauf genügt --repository <url>. Auch Vorgaben wie das Papierformat liegen bei tlmgr: tlmgr paper a4 stellt alle Werkzeuge zugleich auf A4 um (programmweise tlmgr dvips paper a4). tlmgr option show zeigt die aktuellen Einstellungen gesammelt.
# Where tlmgr fetches from, and other stored defaults
tlmgr option repository ctan # automatic CTAN mirror redirection
tlmgr option repository https://example.org/CTAN/systems/texlive/tlnet
tlmgr option show
# Use a different mirror for one run only
tlmgr install --repository https://example.org/CTAN/systems/texlive/tlnet siunitx
# Paper size defaults are stored here too
tlmgr paper a4
tlmgr dvips paper a4TEXMFHOME gegenüber TEXMFLOCAL
Dateien, die tlmgr nicht verwaltet – eine Klassendatei einer Konferenz, ein selbst geschriebener Stil, ein von Hand aus CTAN geholtes Paket –, gehören an einen von zwei Orten: TEXMFHOME nur für einen selbst, TEXMFLOCAL für den ganzen Rechner. Beide werden vor dem Baum der Distribution (TEXMFDIST) durchsucht, eine gleichnamige Datei dort gewinnt also. Die tatsächlichen Orte unterscheiden sich; besser ausgeben lassen als annehmen. Auf diesem Mac liefert kpsewhich -var-value=TEXMFHOME /Users/wedd/Library/texmf – nicht ~/texmf. Unter Linux ist ~/texmf die Vorgabe, weshalb wörtlich befolgte Linux-Anleitungen auf einem Mac dazu führen, dass die Datei dauerhaft unsichtbar bleibt. TEXMFLOCAL liegt hier unter /usr/local/texlive/texmf-local, und bemerkenswert ist: Es steht außerhalb des Jahresverzeichnisses – was dort abgelegt wird, überlebt also den Wechsel auf den nächsten Jahrgang.
# Never guess these paths - print them
kpsewhich -var-value=TEXMFHOME # your own tree (differs on macOS and Linux)
kpsewhich -var-value=TEXMFLOCAL # machine-wide tree, outside the year directory
kpsewhich -var-value=TEXMFDIST # the distribution itself - do not edit by hand
# The whole search order, including the !! markers
kpsewhich -expand-path='$TEXMF'Die Wahl ist einfach: Dateien für die eigenen Manuskripte gehören nach TEXMFHOME; was auf einem gemeinsam genutzten Rechner allen zur Verfügung stehen soll, nach TEXMFLOCAL. TEXMFHOME braucht keine Administratorrechte und wandert bei einer Neuinstallation mit dem Heimatverzeichnis mit. Innerhalb gilt dieselbe Anordnung wie in der Distribution (die TDS): Ein LaTeX-Stil kommt unter tex/latex/. Das Gesamtbild dieser Anordnung gehört zu „TeX-Verzeichnisstruktur und -Pfade“; in der Praxis genügt meist die Hierarchie aus dem folgenden Beispiel. Eine Warnung: Keine alte Kopie einer .sty-Datei im Manuskriptordner liegen lassen. TeX durchsucht das aktuelle Verzeichnis zuerst, sodass die veraltete Kopie auch nach einem tlmgr-Update weiterhin gewinnt – ein sehr schwer aufzuklärender Fehler.
# A personal class file, in the tree that belongs to you
HOME_TREE="$(kpsewhich -var-value=TEXMFHOME)"
mkdir -p "$HOME_TREE/tex/latex/local"
cp mythesis.cls "$HOME_TREE/tex/latex/local/"
kpsewhich mythesis.cls # should print the path immediately
# Let tlmgr manage that tree too, with no root required
tlmgr init-usertree
tlmgr --usermode install siunitxWann mktexlsr und texhash wirklich nötig sind
Die Antwort ist klar: nötig, wenn eine Datei von Hand in TEXMFLOCAL oder einen Systembaum gelegt wurde; nicht nötig, wenn sie in TEXMFHOME liegt. Der Grund ist das !! vom Anfang. Wird TEXMF auf diesem Rechner expandiert, steht !! vor /usr/local/texlive/texmf-local und texmf-dist, nicht aber vor ~/Library/texmf. !! weist kpathsea an: „Für diesen Baum die Platte nicht ansehen, nur der ls-R-Datenbank trauen.“ Somit existiert eine neue Datei so lange nicht, wie ls-R nicht erneuert wurde. Bestätigt wird das dadurch, dass TEXMFDBS, die Liste der Bäume mit ls-R, TEXMFHOME gar nicht enthält. Und der Index lohnt sich: texmf-dist/ls-R umfasst hier 276.953 Zeilen – deshalb muss TeX nicht bei jedem Lauf über 220.000 Dateien durchlaufen.
Der Befehl, der den Index neu aufbaut, heißt mktexlsr; er erzeugt ls-R für jeden in TEXMFDBS genannten Baum neu. texhash ist kein anderer Befehl – auf diesem Rechner nachgeprüft, ist texhash ein symbolischer Link auf mktexlsr, also buchstäblich dasselbe Programm unter zwei Namen. Beide gehen. Da in Systembäume geschrieben wird, ist sudo nötig. Zu beachten ist außerdem, dass tlmgr und getnonfreefonts die Auffrischung selbst erledigen – von Hand aufgerufen wird der Befehl in der Praxis nur nach dem eigenhändigen Kopieren von Dateien.
# The same file in the system tree DOES need the index rebuilt
LOCAL_TREE="$(kpsewhich -var-value=TEXMFLOCAL)"
sudo mkdir -p "$LOCAL_TREE/tex/latex/local"
sudo cp mythesis.cls "$LOCAL_TREE/tex/latex/local/"
sudo mktexlsr # texhash is a symlink to this same program
kpsewhich mythesis.cls # now it resolves
kpsewhich -all mythesis.cls # and shows every copy, if several collideVon Hand aus CTAN installieren: .dtx und .ins
Von Hand geschieht das nur für Dinge, die tlmgr nicht hat: eine Klassendatei, die eine Zeitschrift selbst verteilt, ein vorige Woche veröffentlichtes Paket, eine Fassung, die es nur auf der Seite der Autorin gibt. Manche CTAN-Pakete liefern eine einfache .sty-Datei, viele kommen jedoch als Paar – .dtx, das Quelltext und Dokumentation gemeinsam enthält, und .ins, die Anweisungsdatei zum Auspacken. tex foo.ins erzeugt dann foo.sty aus der .dtx; diese Datei wandert anschließend an die passende Stelle unter TEXMFHOME. Das .dtx-Format ist literate programming in Reinform: pdflatex foo.dtx liefert ein PDF-Handbuch mit dem kommentierten Quelltext darin.
# A package that ships as .dtx + .ins: extract, then place
tex foo.ins # writes foo.sty (and foo.cls, if any)
pdflatex foo.dtx # optional: build the annotated manual
HOME_TREE="$(kpsewhich -var-value=TEXMFHOME)"
mkdir -p "$HOME_TREE/tex/latex/foo"
cp foo.sty "$HOME_TREE/tex/latex/foo/"
kpsewhich foo.styBei MiKTeX: mpm und die automatische Installation
MiKTeX kennt kein tlmgr. Die Kommandozeile heißt mpm (MiKTeX Package Manager), die grafische Oberfläche MiKTeX Console; Aktualisierungen wie Paketergänzungen laufen über diese beiden. Der auffälligste Unterschied ist die Sofortinstallation: Ein vom Dokument angefordertes, aber nicht vorhandenes Paket wird mitten im Lauf heruntergeladen, und die Übersetzung geht weiter (in der Console wählbar: immer installieren, jedes Mal fragen, nie). Diese Automatik hat allerdings eine Bedingung: Selbst wenn MiKTeX für alle Benutzer installiert wurde, landen spontan geholte Pakete im AppData\Roaming des ausführenden Benutzers. Auf gemeinsam genutzten Rechnern also besser vorab im Administratormodus installieren, was gebraucht wird.
Font-Maps verwalten: updmap und getnonfreefonts
Eine Font-Map ist eine zeilenweise Tabelle nach dem Muster: „Die Schrift, die TeX unter diesem Namen anspricht, ist in Wahrheit jene Datei, und so wird sie in das PDF eingebettet.“ Es gibt pdftex.map für pdftex und dvipdfmx, psfonts.map für dvips, kanjix.map fürs Japanische und weitere. Von Hand geschrieben wird das nie – updmap erzeugt diese Dateien. Zur Größenordnung genügt ein Blick auf die Zeilenzahl: pdftex.map umfasst auf diesem Rechner 45.443 Zeilen. Erst wenn ein Schriftpaket installiert wurde und updmap gelaufen ist, ist diese Tabelle aktuell und die Schrift lässt sich in ein PDF einbetten.
updmap hat zwei Gesichter – updmap-sys für das ganze System und updmap-user nur für einen selbst –, und hier lauert die unangenehmste Falle in der Konfiguration von TeX Live. updmap --help warnt selbst davor: Wurde updmap-user auch nur ein einziges Mal ausgeführt, hat ein späterer Aufruf von updmap-sys keinerlei Wirkung mehr. Es entsteht eine persönliche Konfigurationsdatei, die die systemweite fortan verdeckt. updmap-sys gibt in diesem Fall zwar eine Warnung aus, doch wer die Ursache nicht kennt, rätselt sehr lange, warum der Aufruf mit Administratorrechten nichts ändert. Die sichere Regel lautet: nur updmap-sys verwenden und updmap-user gar nicht erst anfassen.
Für das Einbetten japanischer, chinesischer und koreanischer Schriften gibt es einen eigenen Zugang: kanji-config-updmap-sys. Es ruft im Hintergrund updmap auf und schaltet um, welche CJK-Schriftfamilie in die PDF-Dateien eingebettet wird. Mit status meldet es den aktuellen Zustand – auf diesem Rechner ist die japanische Familie derzeit haranoaji, als umschaltbare Kandidaten erscheinen haranoaji, ipa und ipaex. Mit anderen Worten: Die japanischen Schriften, die TeX Live mitbringt, sind Harano Aji sowie IPA / IPAex, und Noto CJK und Source Han sind nicht enthalten. Wer diese nutzen will, verweist auf die im Betriebssystem installierten Schriften oder installiert sie eigens.
# Ask, without changing anything: which CJK family is embedded?
kanji-config-updmap-sys status
# Switch the embedded Japanese family, machine-wide
sudo kanji-config-updmap-sys haranoaji
# Rebuild the map files after a manual font install
sudo updmap-sys # never updmap-user: it permanently shadows updmap-sysZum Schluss die Schriften, die nicht mit der Distribution mitreisen dürfen. Eine Schrift mit der Lizenz „frei nutzbar, aber nicht verkäuflich“ lässt sich nicht in TeX Live bündeln, das auch auf einer verkauften DVD vertrieben wird. Genau dafür gibt es das Skript getnonfreefonts von TUG: Es holt Schrift und TeX-Unterstützungsdateien von CTAN und richtet alles so ein, dass TeX sie findet. Entscheidend ist --user (nach TEXMFHOME) gegenüber --sys (in den Systembaum). Den eigenen Befehl getnonfreefonts-sys, der in älteren Anleitungen auftaucht, gibt es nicht mehr – für alle auf dem Rechner wird getnonfreefonts --sys … mit Administratorrechten ausgeführt. --lsfonts listet auf, was zur Verfügung steht.
# See what is on offer, then install into your own tree
getnonfreefonts --user --lsfonts
getnonfreefonts --user luximono
# Or system-wide, for everyone on the machine
sudo getnonfreefonts --sys luximono- Allgemeine Pakete mit
tlmgrinstallieren. Eine veraltete Kopie im Manuskriptordner gewinnt auch nach einem Update weiter und erzeugt Fehler, die niemand erklären kann. - Dateien, die nur zu einer Konferenzvorlage gehören, dürfen im Manuskript-Repository liegen, weil sie zum Einreichungspaket gehören und nicht zur Distribution.
- Auf gemeinsam genutzten Rechnern und in der CI gehören TeX-Live-Jahrgang, zusätzliche Paketnamen und ein festgelegtes Repository oder Docker-Tag in die README oder
.latexmkrc. „Ich habe es einmal auf meinem Laptop installiert“ ist keine Reproduzierbarkeit. - Kurz vor einer Abgabe kein
tlmgr update --self --allausführen. Sonst entsteht das PDF mit anderen Paketen als gestern. Aktualisierungen an einem anderen Tag ausprobieren. updmap-usernie verwenden. Ein einziger Aufruf genügt, damitupdmap-syswirkungslos bleibt – und die Ursache ist danach ausgesprochen schwer zu finden.