Create a local texmf tree in MiKTeX

Question

In TeX Live there are TEXMFLOCAL for admin and TEXMFHOME for user pre-defined, but in MiKTeX there’s by default no local texmf tree installed, though it is useful, cf. Purpose of local texmf trees. Therefore my question:

How do I create a local texmf tree in MiKTeX?

Answer 1

Actually you can create more than one local TeXMF folder! There’s already a description on MiKTeX’ online documentation, see Integrating Local Additions, at time of writing for recent MiKTeX 2.9 (but the included images are from an older version, seemingly MiKTeX 2.5, and slightly different, cf. also http://docs.miktex.org/2.5/manual/localadditions.html ). The denomination there is “User-Managed TEXMF Directory” (see also additional note at the very end of this answer).

Anyway, here an alternative description:

• Create a folder somewhere on your computer – with an important exception. It must not be a subfolder of your MiKTeX installation (it worked this way in older MiKTeX versions, but was changed for security reasons). Avoid as far as possible spaces in the path, it is a potential risk for malfunction. For use with MiKTeX portable the folder must be, of course, on the same drive as the MiKTeX installation, it will be saved as relative path. Here I will use c:\localtexmf.

  This folder must be TDS compliant (see thereto A Directory Structure for TeX Files); MiKTeX will complain, if not. What you need, depends on what you want to install into this directory, at least a tex\latex subtree should be sufficient. You will go safe, if you mimic the structure of the (itself TDS compliant) MiKTEX tree, but binaries can directly go into a subfolder c:\localtexmf\bin.

• Now, using the GUI:

  1. In the Start Menu go to the MiKTeX entry and open the settings – if you act as admin respectively “Settings (Admin)”, of course. The “MiKTeX Options” window will open.

  2. Go to the “Roots” tab. Click on “Add” and choose c:\localtexmf\. If there are more than one local directory, one can choose the search order with the “Up” and “Down” buttons.

  3. Now the almost most important part: Go to the “General” tab and click there on “Refresh FNDB” (FNDB = File Name Data Base). In some cases, especially if new fonts are installed, one has to press also the “Update Formats” button.

  If you’d forget this step, all earlier steps would be done to no purpose.

• Otherwise, using the command line (as admin always add the switch --admin):

  Execute initexmf --register-root=c:\localtexmf, followed by initexmf --update-fndb (shorter: initexmf -u).

  (In every step you can add the switch --verbose to get more information about, what happens.)

  Remark: For compatibility reasons there’s also the older switch --user-roots=<local-texmf-dir>, what according to initexmf --help registers user root directories, I assume also in administrative mode, but in http://docs.miktex.org/manual/initexmf.html it is not mentioned any more, so I must guess.

• In the case, a bin subfolder for binaries was created, it should be registered in the environment variable %PATH% before the binaries subtree of MiKTeX own installation, see e.g. How To Manage Environment Variables in Windows XP or a third-party tool like Env-Man or RapidEE. Then you need a system restart to take effect. An issue, that cannot be solved: A system wide environment variable, set by an admin, is always read before a user specific one. Then as a simple user you can only write and use batch files with an own %PATH% included.

All user created local texmf trees can be disabled by temporary removing from the MiKTeX roots (cf. additional note at the end).

See also How can I manually install a package on MiKTeX (Windows).

For the sake of completeness, here’s a description, how to remove a local TeXMF tree from MiKTeX, with c:\localtexmf\ as example:

• GUI:
  Go again to the “Roots” tab in the settings (“MiKTeX Options” dialogue), select the directory c:\localtexmf\, and click on “Remove” on the lower side of the window. After that you must again refresh the FNDB and perhaps update the format files.

• Command line (also here: as admin add the switch --admin):
  Execute initexmf --unregister-root=c:\localtexmf, followed by initexmf --update-fndb. If you have uninstalled a font, additionally execute initexmf --mkmaps. The --verbose switch can be added, as well.

• If you do not need the bin subfolder anymore, the environment variable %PATH% must be cleaned up.

• Then the folder tree c:\localtexmf\ could safely be deleted.

Additional Note

^{A hint first: In Command Prompt you can type echo %Variable% with %Variable% e.g. %Userprofile%. So you can see to which value the variables expand on your system.}

Precisely the phrase “in MiKTeX there’s by default no local texmf tree installed”  in the question is not true. MiKTeX adds itself several trees under %UserProfile% and in admin mode also to %AllUsersProfile% (in the following the MiKTeX denomination comes first):

• “UserConfig”: %AppData%\MiKTeX\<version>\
• “UserData”: %LocalAppData%\MiKTeX\<version>\ (since Windows Vista) or %UserProfile%\<Local Settings>\<Application Data>\MiKTeX\<version>\ (until Windows XP, the strings <Local Settings> and <Application Data> are language dependent)
• only in admin mode used “CommonConfig” and “CommonData”: %AllUsersProfile%\MiKTeX\<version>\ (since Windows Vista) or %AllUsersProfile%\<Application Data>\MiKTeX\<version>\ (until Windows XP, the string <Application Data> is language dependent)

The actual paths you can see with the GUI in the “MiKTeX Options” window under the “Roots” tab or with the command line interface by executing initexmf --report.

Disadvantages of all these local trees: They can only be changed on installation, cf. Changing the location of auto-installed packages in MiKTeX, and they cannot be disabled (by temporary removing from the MiKTeX roots).

For additional information see Difference between administrative and user mode of MiKTeX.