LaTeX in VSCode with Chinese Support

Introduction

I was looking for a local alternative for Overleaf, where I came across the LaTeX-Workshop extension for VSCode with LaTeX live preview support. You could follow the official installation guide to setup LaTeX-Workshop, however by default the extension uses pdfLaTeX as the default TeX Engine (compiler for .tex files), which is unicode unfriendly. So this post shows step by step how to setup your Computer and VSCode with unicode LaTeX support using XeLaTeX.

Steps

1. Install a LaTeX distribution (TeX Live)

In this tutorial I’ll download TeX Live distribution as recommended by author of LaTeX-Workshop. A LaTeX distribution will include all LaTeX engine and packages we need.

💡

Download TeX Live here base on your operating system.

For me, I will download the macOS variant of TeX Live: MacTeX. The full version of MacTex is rather large at 6.0G, so it will take a while to download.

After downloading the pkg file, double click and follow the instructions to install it.

Now we can already use some TeX GUI bundle in TeX Live like TeXShop and LaTeXiT, but to use it in VSCode there are some extra steps.

2. Add binaries to PATH

The following guide is for mac or linux, to add program to PATH in Windows follow here.

After we successfully installed LiveTex the binaries will be installed to the following directory:


/usr/local/texlive/<version>/bin

# e.g. 
/usr/local/texlive/2025/bin

We need to add this path to the PATH environment variable so that our shell program can use it, this can be done by add the following line to the configuration file of your shell.


export PATH=/usr/local/texlive/2025/bin:$PATH

A simple way of doing this to run one of the following command in your terminal:


# For zsh users
echo "export PATH=/usr/local/texlive/2025/bin:\$PATH" >> ~/.zshrc

# For bash users
echo "export PATH=/usr/local/texlive/2025/bin:\$PATH" >> ~/.bashrc

Now let’s verify if the installation is successful, by reopening a new terminal window and enter the following command:


xelatex --version

If you see something like the following then you installed it correctly.

3. Install LaTeX-Workshop

If your don’t already have VS-Code installed, download it here.

We can install LaTeX-Workshop by searching it in the extension shop of VSCode, or simply following the redirect in this link. If the extension is successfully installed you should see this page.

Now you should already be able to compile english LaTeX file, but to support other unicode languages like Chinese we need to modify some settings of LaTeX-Workshop.

4. Extension Settings

Open the setting’s page of VSCode and search for @ext:James-Yu.latex-workshop tool then click “Edit in settings.json”.

Now in settings.json add the following property to latex-workshop.latex.tools


{
    "name": "xelatex",
    "command": "xelatex",
    "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "%DOC%"
    ]
},
{
		"name": "bibtex",
		"command": "bibtex",
		"args": [
				"%DOCFILE%"
		]
}

Then scroll up (or down) to find the latex-workshop.latex.recipes property and add the following to the top of the list:


{
		"name": "xelatex",
    "tools": ["xelatex"]
},
{
		"name": "xe->bib->xe->xe",
		"tools": [
				"xelatex",
				"bibtex",
				"xelatex",
				"xelatex"
		]
},

Now we be compile and preview LaTeX / BibTeX project with a simple click.

5. Additional package

To compile LaTeX files with Chinese characters, we need to import an additional package called xeCJK which providing support for multiple asian languages. A simple latex template can be:


\documentclass[letterpaper,11pt]{article}

\usepackage{fontspec}
\usepackage{xeCJK}

\begin{document}


\end{document}