LaTeX is a document preparation system for high-quality typesetting, perfect for academic papers and technical docs. Many people turn to Overleaf as their go-to online editor for LaTeX, but it comes with its own frustrations. If you are tired of Overleaf being costly and always hitting the compile timed out error, this guide is for you!
The full MacTeX install weighs in at a massive ~6.4GB, most of which you'll never actually use. Setting up a minimalist LaTeX environment on macOS using BasicTeX and VSCode is a much better alternative that makes your setup ~8 times smaller. It saves storage and makes it much easier to collaborate with your teammates using GitHub as a combo.
Install LaTeX via Homebrew
We'll use Homebrew to keep things manageable. If you don't have it, grab it at brew.sh.
1. Install LaTeX
BasicTeX is the "lean" version of MacTeX. It's only ~140MB initially.
brew install --cask basictex
2. Refresh your path and verify
Make the TeX binaries available in your current terminal session:
eval "$(/usr/libexec/path_helper)"
The default LaTeX compiler pdflatex should be available now. Verify it's working:
which pdflatex
pdflatex --version
3. Update tlmgr and packages
tlmgr is the TeX Live Manager. To update tlmgr and all packages, run the following commands:
sudo tlmgr update --self
sudo tlmgr update --all
4. Install latexmk (build manager)
latexmk is the "build manager" that handles multiple runs of the compiler (necessary for bibliographies and tables of contents).
sudo tlmgr install latexmk
Verify latexmk version:
which latexmk
latexmk --version
5. Install essential package collections
BasicTeX is too bare-bones for real projects. Since we went minimalist, we need to grab only the packages we actually use. These three collections will cover 90% of your needs while keeping storage down.
sudo tlmgr install collection-latexrecommended
sudo tlmgr install collection-fontsrecommended
sudo tlmgr install collection-latexextra
Note: If a build fails due to a missing .sty file, just run
sudo tlmgr install <pkgname>.
This setup keeps the total size around ~770MB, allowing you to stay lean and only add specific packages as you go.
Set Up VSCode
1. Install LaTeX Workshop extension
Search and install the LaTeX Workshop extension from the Visual Studio Code Marketplace.
2. Create main.tex
To start and test your setup, create a new main.tex file.
\documentclass{article}
\begin{document}
Hello, LaTeX world!
This is a simple test document.
\end{document}
To compile, use the Build LaTeX project button or run pdflatex main.tex from the terminal.
3. Change LaTeX compiler (Optional)
To use a different engine like XeLaTeX, create a file named latexmkrc in the same folder as your project.
# latexmkrc - Custom LaTeX Build Settings
# Put this file in the same folder as your main.tex
# Override default PDF engine (e.g., xelatex)
$pdflatex = 'xelatex -synctex=1 -interaction=nonstopmode -file-line-error %O %S';
# Force PDF output mode (not DVI/PostScript)
$pdf_mode = 1;
Note: Make sure to install the specific engine beforehand (e.g., run
sudo tlmgr install xetex).
LaTeX compilers
Here are some of the most popular LaTeX compilers. You can choose the one that best fits your needs:
| Compiler | Description | Font Support | Unicode | Best Use Case |
|---|---|---|---|---|
| pdfLaTeX | Original PDF output engine | Limited (Type1) | No | Standard documents, broad compatibility |
| LaTeX | DVI output (legacy) | Limited | No | Old workflows, DVI output |
| XeLaTeX | Modern Unicode engine | System fonts | Yes | Modern docs, OpenType |
| LuaLaTeX | Lua scripting + Unicode | System fonts | Yes | Advanced scripting, modern |
References
[1] TeX Users Group, "TeX Live," [Online]. Available: https://tug.org/texlive.
[2] "MacTeX-no-gui," Homebrew Formulae, [Online]. Available: https://formulae.brew.sh/cask/mactex-no-gui.
[3] J. Yu, "LaTeX-Workshop," GitHub, [Online]. Available: https://github.com/James-Yu/LaTeX-Workshop.
[4] "How to use the command 'tlmgr update' (with examples)," CommandMasters, [Online]. Available: https://commandmasters.com/commands/tlmgr-update-common.
Top comments (0)