TinyTeX: A lightweight and easy-to-maintain LaTeX distribution

# A lightweight, cross-platform, portable, and easy-to-maintain LaTeX distribution based on TeX Live

The installation and maintenance of LaTeX have bothered me for several years. Yes, there are MiKTeX, MacTeX, and TeX Live, but the common problems are:

1. You have to either install a basic version that is relatively small (several hundred MB) but basically doesn’t work, because it is very likely that certain frequently used LaTeX packages are missing; or you install the full version that is several GB, but in your whole life, you probably will only use 1% of the packages.

2. The documentation for installation and maintenance is often way too long for beginners. For example, I doubt if anyone has the courage or patience to read the tlmgr manual (yes, it is very useful, thanks to the TeX Live team).

Fortunately, there is a nice way out based on TeX Live. TeX Live is great: it is cross-platform (yes, it works on Windows, too), and it can be portable. We just need to make it lightweight, and easier to maintain.

## Philosophy

TinyTeX is a custom (and probably opinionated) LaTeX distribution based on TeX Live that is small in size but still functions well in most cases. Even if you run into the problem of missing LaTeX packages, it should be super clear to you what you need to do. You only install LaTeX packages you actually need. The manual should be at most two pages long.

Please note that TinyTeX assumes that you are not afraid of using the command line. If you are, please use other popular LaTeX distributions instead. In fact, there is only one single command that you need to know: tlmgr. It is probably not too scary.

TinyTeX only provides an installation script that downloads and installs TeX Live over the network. It may take a couple of minutes, depending on your network speed. Before you install TinyTeX, I recommend that you uninstall your existing LaTeX distribution. Currently TinyTeX works best for R users, but it should not be too hard for other users to use.

## For R Users

Installing and maintaining TinyTeX are easy for R users, since the R package tinytex has provided wrapper functions.1 To install TinyTeX:

install.packages(c('tinytex', 'rmarkdown'))
tinytex::install_tinytex()


What install_tinytex() does will be explained later. If you need to uninstall TinyTeX, run tinytex::uninstall_tinytex(). To compile an R Markdown document to PDF, there is nothing else you have to know. To compile a LaTeX document to PDF, call one of these functions (depending on the LaTeX engine you want to use) in tinytex: pdflatex(), xelatex(), and lualatex(). If these functions detect LaTeX packages required but not installed in TinyTeX, they will automatically install the missing packages by default.

tinytex::pdflatex('test.tex')


## For Other Users

### Installation

For Linux users, TinyTeX will be installed to $HOME/.TinyTeX and symlinks of executables (such as pdflatex) are created under $HOME/bin, which should be on the PATH environment variable:2

wget -qO- \
"https://github.com/yihui/tinytex/raw/master/tools/install-unx.sh" | sh


For macOS users, TinyTeX will be installed to ~/Library/TinyTeX, and executables are symlinked to /usr/local/bin:

curl -sL \
"https://github.com/yihui/tinytex/raw/master/tools/install-unx.sh" | sh


For Windows users, save the batch file install-windows.bat (open this link and press Ctrl + S), and double click it.3 Please note that it requires PowerShell (at least version 3.0). If your Windows version is too low and does not have PowerShell, follow this article to install it. There might be an error dialog or two about luatex.dll during the installation (like this), but that does not seem to hurt, and I just clicked “OK”. The installation directory is %APPDATA%/TinyTeX, where APPDATA is an environment variable that typically points to the path C:\Users\Your Name\AppData\Roaming.4

To uninstall TinyTeX, simply delete the folder from your file manager/browser, or use command line:

# Linux
tlmgr path remove
rm -r "~/.TinyTeX"

# macOS
tlmgr path remove
rm -r "~/Library/TinyTeX"

# Windows
tlmgr path remove
rd /s /q "%APPDATA%\TinyTeX"


Compare the way to uninstall TinyTeX with the ways to uninstall other LaTeX distributions, and you may appreciate how much simpler it is to get rid of TinyTeX than other LaTeX distributions. That is because TinyTeX is just a self-contained folder.

### Maintenance

This section is only for those who are not R Markdown users — everything is automatic for R Markdown users, and you don’t need to manually search for or install missing LaTeX packages.

If you compile a LaTeX document and run into an error message like this:

! LaTeX Error: File framed.sty' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: sty)


It basically indicates a missing LaTeX package. Do not panic. Open a command window, and use the command tlmgr search --global --file followed by the filename,5 e.g.,

\$ tlmgr search --global --file "/framed.sty"
framed:
texmf-dist/tex/latex/framed/framed.sty
...


Find the package that contains the file with the exact name in the error log above. In this case, the missing package is framed (not mdframed or other packages), and we can install a package via tlmgr install, e.g.,

tlmgr install framed


If you still see error messages that you don’t understand, you may update everything:

tlmgr update --self --all
fmtutil-sys --all


For R users, you can use the corresponding helper functions. Some examples:

library(tinytex)
tlmgr_search('/framed.sty')  # search for framed.sty
tlmgr_install('framed')      # install the framed package
tlmgr_update()               # update everything (usually not necessary)


If you see an error message “Remote repository newer than local”, it means you need to upgrade (reinstall) TinyTeX:

devtools::install_github('yihui/tinytex')
tinytex::reinstall_tinytex()


That is all for an average user. Read the FAQ page if you wish to know more technical details about TinyTeX.

## Acknowledgements

I’d like to thank the TeX Live team for the great work, without which TinyTeX wouldn’t be possible. I’m particularly grateful that they offered the options to remove source code and documentation from the installation.

I cannot thank Peng Zhao and Miao Yu enough for their extremely careful and patient testing as well as the very useful feedback. Several other users also helped test the beta version, including Carl Boettiger, TC, Ce Gao, and Xiangyun Huang.

1. Note that when we say tinytex (lower case), we mean the R package. TinyTeX means the LaTeX distribution.
2. If not, you know how to add it to PATH, just because you are a Linux user!
3. You anti-virus software might warn against certain *.dll files, and you may want to trust these files. However, I’m not a Windows expert, so I’ll leave the decision to yourself.
4. Click the Start menu, Run, type cmd to open a command window, and type echo %APPDATA% to figure out the actual path if you are curious.
5. Add a forward slash before the filename for an exact match. Without the slash, other packages may be matched, e.g., mdframed.sty`.