Set Up a LaTeX Environment in 10 Minutes with Docker on Windows

kanpachioishi — Sat, 28 Mar 2026 02:05:35 +0000

Introduction

Ever tried to set up LaTeX and got stuck before writing a single document?

When you install TeX Live directly, you run into path issues, version mismatches, and confusing configuration files. On top of that, the installation itself can take a very long time on Windows.

In this guide, I'll show you how to set up a LaTeX environment using Docker — and it only takes about 10 minutes.

Why Docker?

Fast — In my experience, it took only about 10 minutes from start to finish
Simple — Just a few commands. No path configuration or version management headaches
Reproducible — Anyone can recreate the exact same environment. Easy to start over if something goes wrong
Clean — No massive TeX Live installation on your system. Everything stays inside the Docker container

Don't worry if you've never used Docker before. Just follow the steps in this guide, and you'll be compiling LaTeX documents in no time.

Note: This guide is based on my actual experience setting up LaTeX on a freshly reset Windows PC. I've included the gotchas and errors I encountered along the way, so hopefully you won't have to struggle with the same issues.

Prerequisites

OS: Windows 10 (version 2004 or later) or Windows 11
RAM: 8 GB or more recommended
Storage: At least 5 GB of free space

That's all you need.

Overview

There are three main steps:

1. Enable WSL2 (installs Ubuntu)
2. Install Docker on Ubuntu
3. Pull the LaTeX Docker image and start using it

Everything is done via the command line. No GUI installers needed.

Let's get started.

Step 1: Enable WSL2

What is WSL2? How is it different from WSL?

WSL (Windows Subsystem for Linux) lets you run Linux on Windows. WSL2 is the second version.

	WSL1	WSL2
How it works	Translates Linux calls to Windows	Runs a real Linux kernel in a lightweight VM
Performance	Fast file I/O, but limited compatibility	Near-native Linux performance, Docker support
Docker	Not supported	Supported

Docker requires WSL2. When you run wsl --install, it automatically installs WSL2, so you don't need to worry about choosing.

1-1. Open PowerShell as Administrator

Search for "PowerShell" in the Start menu and select "Run as administrator".

1-2. Install WSL2

Run the following command:

wsl --install

This enables WSL2 and installs Ubuntu in one step.

If WSL2 is already installed, you'll see a message saying so. Just move on to the next step.

Getting "WSL install may be corrupted" error?

When I tried this on a freshly reset PC, I got a "WSL install may be corrupted" error after running wsl --install. Sometimes it appeared right away, sometimes after about a minute — so don't panic if nothing happens for a bit.

The message says "Press any key to start WSL repair", but it times out after 60 seconds. Press a key as soon as you see the message.

After the repair completes, run wsl --install again and it should work fine.

1-3. Set Up Ubuntu

After installation, you'll be prompted to create a username and password. You can do this in PowerShell, but since we'll be working in Ubuntu from here on, you can close PowerShell.

Search for "Ubuntu" in the Start menu and open it. You'll be asked to set a username and password. Choose whatever you like (this is for Linux, separate from your Windows credentials).

Your password won't show on screen as you type — not even ***. This is normal Linux security behavior. Just type your password and press Enter. You'll be asked to confirm it by entering it again.

Step 2: Install Docker on Ubuntu

From here, work in the Ubuntu terminal. Open "Ubuntu" from the Start menu.

2-1. Update Packages

sudo apt update && sudo apt upgrade -y

What does "sudo" mean?

sudo means "run this command as administrator." You'll need it for installing software and making system changes. When prompted, enter the password you set in Step 1-3.

2-2. Install Docker

sudo apt install -y docker.io

2-3. Allow Your User to Run Docker Without sudo

By default, you need sudo for every Docker command. Fix that with:

sudo usermod -aG docker $USER

What does this command do?

usermod -aG docker $USER adds your current user to the docker group. Members of this group can run Docker commands without sudo.

Close the Ubuntu window and reopen it to apply the change.

I forgot to do this and got a permission denied error when running docker pull. Don't skip this step!

2-4. Verify Docker Is Working

After reopening Ubuntu, check the Docker version:

docker --version

If you see a version number, you're good.

If the Docker daemon isn't running, start it with:

sudo service docker start

Step 3: Pull the LaTeX Docker Image

Still in the Ubuntu terminal.

3-1. Download the Image

docker pull k1z3/texlive

This takes 3-5 minutes on the first run since it's downloading the full TeX Live environment. Grab a coffee while you wait.

3-2. Confirm the Download

docker images

You should see k1z3/texlive in the list:

REPOSITORY       TAG       IMAGE ID       CREATED        SIZE
k1z3/texlive     latest    xxxxxxxxxxxx   X months ago   X.XXGB

Step 4: Set Up a Project Folder

4-1. Create a Folder

mkdir ~/latex-project
cd ~/latex-project

How to access this folder from Windows Explorer

Type \\wsl$\Ubuntu\home\YOUR_USERNAME\latex-project in the Explorer address bar. You can edit files using any Windows text editor (Notepad, VS Code, etc.).

4-2. Create the Required Files

Create these two files in the folder. Use your preferred editor.

Creating files from the Ubuntu terminal

Copy and paste these commands:

Create main.tex:

cat &lt;&lt; 'EOF' &gt; main.tex
\documentclass{article}
\begin{document}
\Huge \LaTeX
\end{document}
EOF

Create .latexmkrc:

cat &lt;&lt; 'EOF' &gt; .latexmkrc
$latex = 'uplatex';
$dvipdf = 'dvipdfmx %O -o %D %S';
$pdf_mode = 3;
EOF

main.tex (your document):

\documentclass{article}
\begin{document}
\Huge \LaTeX
\end{document}

.latexmkrc (build configuration):

$latex = 'uplatex';
$dvipdf = 'dvipdfmx %O -o %D %S';
$pdf_mode = 3;

What is .latexmkrc?

Compiling LaTeX involves running multiple commands in sequence. .latexmkrc is a configuration file that automates this process.

This configuration specifies:

uplatex — The LaTeX engine to use
dvipdfmx — Converts DVI format to PDF
$pdf_mode = 3 — Uses the uplatex -> dvipdfmx pipeline to generate PDFs

Your folder should look like this:

~/latex-project/
├── main.tex
└── .latexmkrc

Step 5: Compile and Generate a PDF

5-1. Make Sure You're in the Project Folder

cd ~/latex-project

5-2. Run the Compiler

docker run --rm -v "$(pwd):/texsrc" -w /texsrc k1z3/texlive latexmk main.tex

What does this command mean?

Option	Meaning
`docker run`	Run a Docker container
`--rm`	Automatically remove the container after it finishes
`-v "$(pwd):/texsrc"`	Mount the current folder to `/texsrc` inside the container
`-w /texsrc`	Set the working directory inside the container
`k1z3/texlive`	The Docker image to use
`latexmk main.tex`	The command to compile `main.tex`

5-3. Check the PDF

If compilation succeeds, main.pdf will be generated in your folder.

Open \\wsl$\Ubuntu\home\YOUR_USERNAME\latex-project in Windows Explorer and double-click main.pdf. If you see "LaTeX" displayed in large text, it worked!

Troubleshooting

"docker: command not found"

Docker isn't installed, or you haven't reopened Ubuntu after Step 2-3. Close and reopen the Ubuntu window, then try again.

"permission denied"

You need to close and reopen Ubuntu after running sudo usermod -aG docker $USER in Step 2-3. The group change won't take effect until you do.

If the error persists after reopening, check that the Docker daemon is running:

sudo service docker start

"Cannot connect to the Docker daemon"

The Docker daemon isn't running. Start it with:

sudo service docker start

How to auto-start Docker on WSL2 startup

On WSL2, you may need to start the Docker daemon manually each time you open Ubuntu. To automate this, add the following to the end of your ~/.bashrc:

if service docker status 2&gt;&amp;1 | grep -q "is not running"; then
    sudo service docker start &gt; /dev/null 2&gt;&amp;1
fi

Note: You'll also need to configure passwordless sudo for this to work silently. Search for "wsl2 docker auto start" for more details.

Summary

Here's what we did:

Enabled WSL2 (wsl --install)
Installed Docker on Ubuntu (sudo apt install docker.io)
Pulled the TeX Live image (docker pull k1z3/texlive)
Created a project folder with .tex and config files
Compiled with docker run

No need to install Docker Desktop or any other GUI application. Everything is done from the command line.

Once this environment is set up, all you need to do is write .tex files and run a single command. Even if you get a new PC, just install WSL2 and Docker, and your environment is instantly recreated.

Happy TeXing!

DEV Community: kanpachioishi