Three Ways to Create Dockernized LaTeX Environment
Getting Started with LeTeX + Docker + VSCode Remote Container

Table of Contents
Introduction
1. Setup
2. Method 1: tianon/latex
3. Method 2: Remote-Containers
4. Method 3: Creating your container
5. How to switch Remote containers
6. Opening a PDF
Conclusion
Introduction
We can run a Docker application in any environment, Linux, Windows, or Mac. Docker provides a set of official base images for the most used operating systems and apps. Docker allows you to take full control of your environment, installing what you need, removing, and installing from Dockerfile.
In this article, I will show you three ways how to use LaTeX on Docker and VSCode Remote Containers extension. In the first part, we use tianon/latex image and qmcgaw/latexdevcontainer Docker image in the second part. In the end, we create our image based on the qmcgaw/latexdevcontainer Docker image.
Setup
If you wish, you can delete LaTeX from your computer.
For me I needed to run:
$ brew uninstall mactex
Please install Docker Desktop and VSCode’s Remote-Containers and LaTeX-Workshop VSCode extension.


Method 1: tianon/latex
Pull tianon/latex image:
$ docker pull tianon/latex
Open settings.json by SHIFT+CMD+P:

And add the following:
{
// ... YOUR OTHER SETTINGS ...
// latex
"latex-workshop.docker.enabled": true,
"latex-workshop.latex.outDir": "./out",
"latex-workshop.synctex.afterBuild.enabled": true,
"latex-workshop.view.pdf.viewer": "tab",
"latex-workshop.docker.image.latex": "tianon/latex",
// End
}
Create a tex file and enter the following:
\documentclass{article}
\begin{document}
An Example for a very \tiny{tiny} \normalsize \LaTeX \ document.
\end{document}
You can build a LaTeX file either by clicking the build icon or using OPTION+CMD+B on Mac.

After that whenever you save a file, it will automatically update the PDF.

Now you are running LaTeX on Docker.
Method 2: Remote-Containers
The Visual Studio Code Remote — Containers extension lets you use a Docker container as a full-featured development environment. It allows you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code’s full feature set. A devcontainer.json file in your project tells VS Code how to access (or create) a development container with a well-defined tool and runtime stack. — from Developing inside a Container
In your directory, create .devcontainer/devcontainer.j
son and add the following:
{
"name": "project-dev",
"dockerComposeFile": ["docker-compose.yml"],
"service": "vscode",
"runServices": ["vscode"],
"shutdownAction": "stopCompose",
"workspaceFolder": "/workspace",
"postCreateCommand": "",
"extensions": [
"james-yu.latex-workshop",
// Git
"eamodio.gitlens",
// Other helpers
"shardulm94.trailing-spaces",
"stkb.rewrap", // rewrap comments after n characters on one line
// Other
"vscode-icons-team.vscode-icons",
],
"settings": {
// General settings
"files.eol": "\n",
// Latex settings
"latex-workshop.chktex.enabled": true,
"latex-workshop.latex.clean.subfolder.enabled": true,
"latex-workshop.latex.autoClean.run": "onBuilt",
"editor.formatOnSave": true,
"files.associations": {
"*.tex": "latex"
},
"latex-workshop.latexindent.args": [
"-c",
"%DIR%/",
"%TMPFILE%",
"-y=\"defaultIndent: '%INDENT%',onlyOneBackUp: 1\"",
]
}
}
In the setting, we enable listing LaTeX with ChkTeX, deleting LaTeX auxiliary files recursively in sub-folders, and we delete LaTeX auxiliary files on built.
If you wish, you can see more setting in VSCode > Preferences > Settings > Extensions > LaTeX.

Create .devcontainer/docker-compose.
yml and add the following:
version: "3.7"
services:
vscode:
image: qmcgaw/latexdevcontainer
volumes:
- ../:/workspace
- ~/.ssh:/home/vscode/.ssh:ro
- ~/.ssh:/root/.ssh:ro
- /var/run/docker.sock:/var/run/docker.sock
environment:
- TZ=
cap_add:
- SYS_PTRACE
security_opt:
- seccomp:unconfined
entrypoint: zsh -c "while sleep 1000; do :; done"
We use qmcgaw/latexdevcontainer
as the image
. It uses texlive 2020 basic scheme and latexmk for LaTeX compilation to PDF. It formats on save using latexindent and uses chktex for LaTeX linting.
You have the following structure:

Click the green icon at the left-bottom, or open the command palette in Visual Studio Code (CMD/CTRL+SHIFT+P), and select Remote-Containers: Open Folder in Container...
and choose your project.


It will pull the Docker image, in this case qmcgaw/latexdevcontainer
, and run a container behind the scene.

Once it is done, you will see “Dev Container” at the bottom left in VSCode.

If you need to install LaTeX packages you can use tlmgr
in the VSCode terminal:
$/workspace tlmgr update --self
$/workspace sudo apk add xz
$/workspace tlmgr install lastpage
$/workspace texhash

Create a simple tex file:
\documentclass{article}
\usepackage{lastpage}
\begin{document}
An Example document.
\[
\frac{4}{12}
\]
\end{document}
And when you save it, it will create a PDF file.

Method 3: Creating your container
qmcgaw/latexdevcontainer is a great starting point to create your Dockerfile and install all packages in your image. Here is an example.
Create a new directory and a Dockerfile in it:
FROM qmcgaw/latexdevcontainer
ARG USERNAME=vscode
USER root
RUN tlmgr update --self && \
tlmgr install latexindent latexmk && \
tlmgr install mathexam setspace adjustbox xkeyval collectbox enumitem lastpage && \
texhash
USER ${USERNAME}
This will update tlmgr
and install all packages I need. We can add any LaTeX packages using tlmgr install ...
.
We build an image from this Dockerfile.
$ docker build -t shinokada/latexexam .
I am running this command from the same directory I have the Docker file.
Let’s check the image we just created.
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
shinokada/latexexam latest 7035f718823c 32 seconds ago 401MB
qmcgaw/latexdevcontainer latest 85b911aaea3e 3 weeks ago 382MB
It has 19 MB more than qmcgaw/latexdevcontainer.
You can push to Docker Hub so that you can use it in the future and share it with others.
$ docker login
...
$ docker push shinokada/latexexam
...
We will update .devcontainer/docker-compose.yml
file so that VSCode uses our new Docker image.
version: "3.7"
services:
vscode:
image: shinokada/latexexam
volumes:
- ../:/workspace
- ~/.ssh:/home/vscode/.ssh:ro
- ~/.ssh:/root/.ssh:ro
- /var/run/docker.sock:/var/run/docker.sock
environment:
- TZ=
cap_add:
- SYS_PTRACE
security_opt:
- seccomp:unconfined
entrypoint: zsh -c "while sleep 1000; do :; done"
The only difference is image: shinokada/latexexam
.
Let’s update .devcontainer/devcontainer.json
. We are going to output PDF to the /out
directory. We use the same file as before and add a line:
...
"settings": {
// General settings
"files.eol": "\n",
// Latex settings
"latex-workshop.chktex.enabled": true,
"latex-workshop.latex.outDir": "./out",
...
Let’s create a sample tex file called percent.tex.
Your directory structure is like this:

Then select “Open Folder in Container” as we did before. It will start Dev Container.
Save the percent.tex file and see a PDF is created in the out
directory.


How to switch Remote containers
When you change files in .devcontainer
directory, you need to rebuild a container. Select “Remote-Containers: Rebuild Container”.

If the above method doesn’t work, you may need to select “Remote-Containers: Reopen Locally” first then select “Remote-Containers: Open Folder in Container”.
Opening a PDF
You can view a tex file in the VSCode tab or web browser. Please note you need to do it from a tex file. If you try to open it from another type of file, it won’t work.

Conclusion
The size of qmcgaw/latexdevcontainer
is 382MB and it is much smaller than tianon/latex
. You can customize your image by creating your Dockerfile and using the FROM
instruction to specify the parent image from which you are building.
Even though the file size of tianon/latex
is big, the advantage of using it is that you don’t need to install packages. It already has most of the standard packages.

Get full access to every story on Medium by becoming a member.
