Creating And Managing Local Texmf Trees In Miktex

The Problem of Customizing Your TeX Installation

If you use LaTeX for any significant amount of time, you will likely find cases where you want to extend or customize your TeX installation. For example, you may need to install custom LaTeX packages, create specialized document classes, add fonts that are not included in your TeX distribution, or make changes to existing BibTeX styles or LaTeX package files. However, making these types of modifications directly in the main TeX directories can cause issues down the line when you upgrade your distribution.

The main directories of your TeX installation, such as texmf-dist in MikTeX, are managed by your TeX distribution and should only contain files provided as part of the distribution. If you make changes here directly, subsequent updates or reconfigurations of your TeX system can overwrite your customizations. Even if they are not overwritten immediately, your changes mix with files provided by the system, making management more complicated and upgrades harder in the long run.

Local TeXMF trees provide an ideal solution to these issues when customizing an installation of MiKTeX. A local TeXMF tree is an additional set of directories you configure which mimics the main TeX directory structure. MiKTeX knows to search local trees when trying to find LaTeX packages, fonts, and more. Any files you provide in a local tree are completely under your control and do not interfere with the main MiKTeX directories.

Setting Up Your First Local TeXMF Tree

Setting up your first local TeXMF tree involves a few steps - determining where to locate it, creating the needed folder structure to mimic the system layout, and configuring MiKTeX to be aware of the custom tree location.

Determining the Location for Your Local Tree

You have flexibility in choosing where to locate your local TEXMF tree folder. Most people create it under their user account's home directory. For example, on Windows you could create it as C:\Users\MyAccount\texmf while on Linux/Unix it could be /home/MyAccount/texmf. This keeps it separated from system files entirely in your user space.

You can use any location you have write access to. An alternative on Windows would be C:\Local TeX Files. The path cannot contain spaces or special characters, so a simple name like texmf or miktex_local works best.

Creating the Folder Structure

Under your chosen local tree location, you need to recreate the same texmf folder structure that exists in the main MiKTeX directories. This includes folders like tex, fonts, bibtex and others. MiKTeX relies on certain paths under texmf to determine where to look for different types of files.

A skeleton hierarchy would look like this:

/texmf
    /bibtex
    /fonts
    /tex
        /latex
        /xelatex        
    /scripts
    /dvips
    /pdftex
    /metapost

You only need to create the particular branches where you will actually place custom files, but mirroring the entire structure above allows room for any possible additions in the future.

Configuring MiKTeX to Recognize Your Tree

The final step is to configure MiKTeX to search your new local texmf tree for TeX files. This is done through the MiKTeX Console utility. Launch the console and go to Settings under the Tasks menu.

Click Add at the top and then set the Folder field to your new tree path (e.g. C:\Users\MyAccount\texmf). Ensure "Recursive" is checked so all subdirectories are scanned, and pick an arbitrary name for the tree like "My Local TeXMF Files".

Click Apply or OK and MiKTeX will now search this tree when trying to locate custom packages, fonts, and more.

Populating Your Local TeXMF Tree

Now that you have set up the local tree structure and configured MiKTeX to index it, you can begin populating it with your own TeX content. What type of content lives in which folders follows the same logic as with the system directories.

Adding Custom .sty and .cls Files

To install a custom LaTeX package or document class, place the .sty and .cls files under texmf/tex/latex. For example, to add a custom thesis document class called mythesis.cls, the path would be texmf/tex/latex/mythesis.cls. Multiple subfolders can be used here to organize collections of custom packages and classes.

Installing Custom Fonts, BibTeX Styles, etc

Extra fonts not included in your TeX distribution should be saved in texmf/fonts whereas BibTeX styles are placed under texmf/bibtex/(bstfiles). Similarly, custom metapost or graphics/diagram code would live under metapost and pdftex respectively.

Using the correct texmf subfolders is crucial for MiKTeX to identify and locate the files later when compiling documents.

Example Directory Structure

As an example, here a subset of files you may add under a local tree:

/texmf 
    /bibtex
        mycustom.bst
    /fonts 
        /myfont
            myfont.tfm
        serif.ttf 
    /tex
        /latex
           /mypackage
                mypackage.sty
           mycustomcls.cls 
        /metapost 
            diagram1.mp

This contains a custom BibTeX style, font files, LaTeX packages/classes, and some Metapost code saved to their respective locations to be available globally in MiKTeX.

Refreshing the File Name Database

Now that you have set up and populated your custom local TeXMF tree, the final step is to get MiKTeX to index all the custom files properly. This achieved by refreshing a system database called the File Name Database or FNDB.

Understanding the File Name Database (FNDB)

The FNDB is a system index that tracks every file MiKTeX knows about across all configured TeXMF trees. When you compile a LaTeX document for example, MiKTeX refers to this database to locate and load the required packages, fonts, and more rather than searching the entire file system directly.

Without the FNDB, MiKTeX would be very slow at trying to locate files. So whenever you make a change like adding a new tree or custom files, the FNDB needs to be updated to make MiKTeX aware of the changes.

Forcing MiKTeX to Refresh the FNDB

In the MiKTeX Console under Tasks, click Refresh FNDB. This will scan all known TEXMF folders, including your new local tree, and rebuild the database.

Alternatively, many MiKTeX utilities have an option to run --mklinks after execution. For example, latex --mklinks myfile would rerun initexmf to refresh the FNDB automatically after a LaTeX run.

Verifying Your Custom Files are Found

As a test, try compiling a simple LaTeX file that loads one of your custom packages or fonts from the local tree. If the FNDB has been updated properly, MiKTeX should locate the custom files successfully without any file not found errors.

If you do receive file not found messages, there may be an issue with permissions, paths, or the FNDB itself. This leads into some common troubleshooting steps discussed next.

Troubleshooting Issues with Local TeXMF Trees

Some common issues can occur when working with local TEXMF trees - such as MiKTeX not being able to locate custom files, or running into permissions errors when trying to access the tree. Here are some tips for debugging these types of problems if they arise.

Debugging if Custom Files are Not Found

If MiKTeX cannot find a file like a custom LaTeX package in your local tree, first verify the FNDB is up to date by forcing a refresh. If that does not resolve the problem, use the MiKTeX Console to check your tree configuration under Settings.

Ensure your local texmf folder path is listed, Recursive mode is enabled, and the name matches whatever you originally configured. If the tree is missing here or not set recursively, this will prevent custom files from being visible to the system.

Fixing Permission Errors or Incorrect Paths

Another common source of issues is file/folder permissions. Your user account needs full read and write access to the entire local TEXMF tree. For example non-admin users can run into permission errors on Windows for the Program Files area.

Double check that the configured path leads to the correct location with your files visible and accessible to the user account that runs MiKTeX. Incorrect capitalization in paths or an outdated tree folder target can also cause problems.

Understanding When to Refresh the FNDB

As a final note - remember that adding new files to an existing local tree does not automatically update the FNDB. You must manually refresh it each time to have MiKTeX index the changes. A quick refresh after any major changes can fix strange errors about missing packages or fonts.

Best Practices for Managing Local TeXMF Trees

Over time, customizing MiKTeX through local TEXMF trees can involve adding hundreds of files across dozens of folders. Here are some tips for keeping this organized and maintainable.

Keeping Your Tree Structure Organized

Even though you have flexibility in naming custom packages or font files for example, stick to logical naming conventions that will make sense months or years later. Add commenting where helpful and follow standard LaTeX guidelines for custom class, package, and utility files.

Also refrain from using deeply nested subfolders just to keep certain groupings of files together. Stick to the standard texmf layout where possible - you can use sister subfolders like texmf/tex/latex/custom1 and texmf/tex/latex/custom2 to separate groups rather than nesting.

Maintaining Multiple Trees Cleanly

For complex use cases, you may benefit from maintaining multiple local trees - for example keeping teacher files separate from student submissions. When taking this approach, adopt a consistent naming scheme across trees to keep things clean.

For example use names like local_john and local_mary for teacher trees and local_class101 for a shared class submission folder.

Avoiding Duplication with Main Tree

Be careful not to accidentally duplicate system files in your local tree - which at best adds clutter and at worst causes compile issues. Restrict custom files to those you create or obtain from outside the MiKTeX distribution itself.

Use MiKTeX package management tools to check whether files exist in the main texmf-dist folder before copying to a local location.