Estructura de directorios y rutas de TeX

Una instalación de TeX es una pila de decenas de miles de archivos: macros, clases, fuentes, configuración. ¿Por qué escribir una sola línea \usepackage{amsmath} encuentra de manera confiable amsmath.sty en algún lugar del disco? Detrás de esto se encuentran dos convenciones: un estándar para saber dónde se encuentran los archivos (el TDS) y un mecanismo para encontrarlos (kpathsea). Esta página dibuja ese mapa.

El TDS: un lugar estándar para todo

Todo comienza desde un árbol de directorios llamado árbol texmf; “texmf” es la abreviatura de *TeX y Metafont*. Debajo, los archivos se ramifican por tipo: las macros y las clases se encuentran en tex/, todo lo relacionado con fuentes en fonts/, los datos bibliográficos en bibtex/, la documentación (manuales) en doc/, los scripts en scripts/. Estandarizar este diseño en todos los sistemas es tarea del TDS (TeX Directory Structure), definido por el TeX Users Group (TUG) en la década de 1990.

¿Por qué tener un estándar? TeX se ejecuta en macOS, Unix, Windows y más, y CTAN (el Comprehensive TeX Archive Network) recopila una enorme pila de paquetes. Si cada sitio organizara los archivos de manera diferente, tanto las personas que envían los paquetes como las herramientas que los encuentran tropezarían cada vez. Una vez que se corrige “las macros viven bajo tex/”, la ubicación de cualquier archivo se puede inferir solo a partir de las reglas, en cualquier OS y cualquier distribución. La portabilidad es exactamente el problema que resuelve el TDS.

Las ramas tienen sus propias reglas. tex/ se divide por formato, luego por paquete, dando tex/<format>/<package>/ (donde <format> es latex, plain, generic,…). El article.cls estándar, por ejemplo, se encuentra en la ruta siguiente, y la herramienta kpsewhich que se presenta más adelante informará la misma ubicación en su propia máquina.

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

Las fuentes van un nivel más fino: fonts/<type>/<supplier>/<typeface>/. El <type> es el tipo de archivo: tfm para métricas de fuentes TeX, vf para fuentes virtuales, además de type1, opentype, truetype, etc. El <supplier> es quien lo proporcionó (public, adobe, ams,…) y <typeface> es el nombre de la fuente (cm = Computer Modern). La siguiente tabla enumera las sucursales con las que se encuentra con más frecuencia y lo que ofrece cada una.

Varios árboles y cuál gana

Un árbol texmf no es una sola cosa. TeX Live agrupa varios árboles con funciones distintas, cada uno nombrado por una variable TEXMF…. ¿Por qué separarlos? Para mantener tres cosas separadas: la distribución (solo lectura, reemplazada al por mayor en cada actualización), lo que agregó (que no debe desaparecer) y datos de trabajo generados automáticamente. Mézclalos y actualizar la distribución podría eliminar tus propios estilos en un instante.

Si un archivo con el mismo nombre existe en varios árboles, ¿cuál gana? Eso lo decide la variable TEXMF, que simplemente enumera la prioridad de búsqueda en orden. Al consultarlo se devuelve aproximadamente la siguiente secuencia (el extremo izquierdo gana):

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

Léalo así: primero su propia configuración (TEXMFCONFIG) y datos de trabajo (TEXMFVAR), luego su árbol personal TEXMFHOME, luego el TEXMFLOCAL de todo el sitio y, finalmente, la configuración del sistema, los datos de trabajo y la distribución TEXMFDIST. Debido a este orden, colocar su propio mystyle.sty en TEXMFHOME hace que ensombrezca la copia de la distribución: sin golpes, solo una clasificación natural de distribución personal → sitio →. (El !! principal se explica en la siguiente sección).

kpathsea: cómo se encuentran los archivos

Incluso con el diseño arreglado, ¿quién encuentra realmente un archivo? Esa es kpathsea (kpse, *kpath search*), la biblioteca de búsqueda de rutas compartida por TeX y sus herramientas complementarias. tex, pdflatex, dvipdfmx, y el resto no buscan por sí solos; Todos preguntan a kpathsea: "¿Dónde está amsmath.sty?"

kpathsea expresa una ruta de búsqueda como una cadena con reglas. Vale la pena conocer tres símbolos: $VAR expande una variable; un // final significa “buscar todo lo que está debajo de esto, de forma recursiva”; y un !! inicial significa “no escanee el disco directamente; consulte solo la base de datos de nombres de archivos que se describe a continuación”. La ruta para encontrar fuentes de LaTeX, TEXINPUTS, en realidad se ve así:

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

Léalo como: busque primero en . (el directorio actual); en su defecto, recurra a través de la rama tex/ de cada árbol texmf en el orden latex → generic → todo lo demás. Esto proporciona el comportamiento intuitivo que espera: un archivo al lado de su manuscrito gana; de lo contrario, recurre a la distribución.

Pero escanear realmente decenas de miles de directorios cada vez sería demasiado lento. Entonces, kpathsea usa una base de datos de nombres de archivos llamada ls-R ubicada en la raíz de cada árbol: una lista de texto de qué archivo se encuentra en qué directorio. Consultar ese índice en lugar de recorrer el disco hace que las búsquedas sean instantáneas. El !! visto anteriormente significa "confiar sólo en el índice (nunca toque el disco real)", y está adjunto a árboles como la distribución que rara vez cambian.

La otra cara: después de agregar un archivo a un árbol, es posible que TeX no lo encuentre hasta que se reconstruya ls-R, especialmente en los árboles del sistema !!. El comando que regenera el índice es mktexlsr, también conocido como texhash. Los árboles personales como TEXMFHOME se tratan con más indulgencia y, a menudo, no necesitan reconstrucción, pero después de poner algo en TEXMFLOCAL, la medida segura es ejecutar la línea siguiente.

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

Cuando algo sale mal, el primer paso es consultar archivos y variables directamente con kpsewhich: "¿qué archivo se está leyendo realmente?" y "¿a qué se expande esta variable?" se responden instantáneamente, lo que le permite aislar una configuración incorrecta. El conjunto completo de opciones de kpsewhich y los comandos de administración como tlmgr se tratan en detalle en una página separada.

PATH: el camino hacia los comandos

kpathsea encuentra los archivos que TeX lee, pero antes de eso el shell debe localizar el ejecutable, pdflatex. Ese es el trabajo de OS: busca en los directorios enumerados en la variable de entorno PATH, en orden. TeX Live mantiene sus ejecutables en un único directorio bin por OS y por arquitectura, y colocarlo en PATH es el toque final de una instalación.

El nombre del directorio incluye el año y la plataforma: en Linux /usr/local/texlive/2026/bin/x86_64-linux, en macOS /usr/local/texlive/2026/bin/universal-darwin, en Windows ...\bin\windows. En macOS, MacTeX proporciona un enlace simbólico estable e independiente del año en /Library/TeX/texbin, por lo que una actualización anual no necesita editar su PATH. Puedes ver a qué apunta actualmente así:

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

Si alguna vez ve “pdflatex: command not found”, nueve de cada diez veces el directorio bin simplemente falta en PATH. El procedimiento OS-by-OS para configurarlo y las comprobaciones posteriores a la instalación se dejan en la página de instalación.

texmf.cnf: de donde provienen las configuraciones

¿De dónde provienen realmente todas las variables hasta ahora (TEXMF, TEXINPUTS, la ubicación de cada árbol)? La respuesta es un archivo de configuración llamado texmf.cnf. Antes de hacer cualquier cosa, kpathsea lo lee para seleccionar los parámetros operativos: las rutas de búsqueda, dónde se ubica cada árbol, límites de memoria y más. La copia maestra se encuentra bajo web2c/ de la distribución:

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

La parte interesante: puede haber más de uno texmf.cnf. kpathsea lee texmf.cnf desde varios lugares a lo largo de una ruta de búsqueda dedicada (la variable TEXMFCNF), en orden, y toma la primera definición que encuentra para cualquier variable determinada (los archivos posteriores no anulan los anteriores). Por lo tanto, deja intacto el gran archivo predeterminado de la distribución y coloca un pequeño archivo de anulación en una ubicación de mayor prioridad: un esquema de capas que agrega solo sus cambios, de forma segura. Agregar -all revela los archivos realmente apilados:

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

Aquí el texmf.cnf superior (la anulación delgada de TeX Live) se lee antes que el texmf-dist/web2c/texmf.cnf inferior (cientos de líneas de valores predeterminados). Cuando desea cambiar un valor de forma permanente, la convención es no editar el archivo de distribución sino escribir solo las líneas que necesita en una ubicación de mayor prioridad como TEXMFLOCAL/web2c/texmf.cnf. Haga eso y su configuración sobrevivirá a una actualización de distribución.

En resumen, así es como TeX encuentra un archivo: texmf.cnf primero corrige dónde están los árboles y cómo se ven las rutas de búsqueda; siguiendo ese orden, kpathsea localiza el objetivo (normalmente mediante el índice ls-R); y PATH proporciona el punto de entrada al propio ejecutable. Estas tres capas se entrelazan para que una sola línea de \usepackage{...} se resuelva silenciosamente.

Dónde poner tus propios archivos

La regla práctica más importante es: no editar el árbol de distribución. Si coloca un thesisstyle.sty solo para tesis o un labreport.cls para todo el laboratorio dentro de /usr/local/texlive/2026/texmf-dist, una actualización o reinstalación puede borrarlo. Coloque los archivos personales en TEXMFHOME, los archivos de todo el laboratorio en TEXMFLOCAL y mantenga el diseño TDS.

Por el contrario, los archivos que pertenecen solo a un paquete de envío (una conferencia myconf.cls o una revista journal.sty) pueden estar junto al manuscrito. TEXINPUTS comprueba primero el directorio actual, por lo que TeX preferirá esa copia. Por eso también es peligroso colocar nombres genéricos como article.cls o un viejo amsmath.sty al lado del manuscrito: ensombrece la distribución y crea fallos que sólo aparecen en otras máquinas.

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

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

Una vez que kpsewhich informa la ruta esperada, el manuscrito puede decir simplemente \usepackage{thesisstyle}. Si no informa nada, verifique en orden: si el archivo se encuentra bajo tex/latex/<package>/, si el nombre del archivo coincide y si mktexlsr se ejecutó para un árbol de sistemas. Esto enmarca el error como "¿dónde lo puse en el mapa de búsqueda?" en lugar de "TeX está roto".