MENU
contact

VSCodeでLaTeXをコンパイルできない原因と対処法

VSCode

採用はこちら

VSCodeでLaTeXをコンパイルできない場合、原因はVSCodeそのものではなく、LaTeX環境や拡張機能の設定にあることが多いです。

特に多いのが、LaTeX本体の未インストール、PATHの設定不足、LaTeX Workshopのレシピ設定、使用するコンパイラの不一致、LaTeXソース内のエラーです。

VSCodeでLaTeXを利用する場合は、VSCodeだけでなく、LaTeX WorkshopとTeX Live・MiKTeX・MacTeXなどのLaTeXディストリビューションも必要になります。

目次

VSCodeでLaTeXをコンパイルするために必要な環境

VSCodeだけではLaTeXをコンパイルできない

VSCodeには、LaTeXを直接コンパイルする機能は搭載されていません。

一般的には、次の3つを組み合わせてLaTeX環境を構築します。

  • VSCode
  • LaTeX Workshop
  • TeX Live・MiKTeX・MacTeXなどのLaTeXディストリビューション

LaTeX Workshopは、VSCodeからlatexmkやpdflatexなどを実行するための拡張機能です。

LaTeXコンパイラ本体を内蔵しているわけではありません。

そのため、LaTeX Workshopだけをインストールしても、TeX Liveなどがインストールされていなければコンパイルできません。

LaTeX本体がインストールされているか確認する

Windowsの場合

Windowsでは、TeX LiveまたはMiKTeXがよく利用されます。

インストール後、VSCodeの統合ターミナルで次のコマンドを実行します。

pdflatex --version

LaTeX Workshopで一般的に使用されるlatexmkも確認します。

latexmk --version

バージョン情報が表示されれば、LaTeX環境がコマンドとして認識されています。

macOSの場合

macOSでは、MacTeXやBasicTeXなどが利用できます。

確認する場合は、次のように実行します。

latex --version
latexmk --version

正常にバージョン情報が表示されれば、LaTeX本体は利用できる状態です。

Linuxの場合

Linuxでも、一般的にはTeX Liveを利用します。

次のコマンドで確認できます。

latex --version
latexmk --version

PATHが通っているか確認する

latexmkが見つからない場合

LaTeXをインストールしていても、VSCodeから実行ファイルを見つけられなければコンパイルできません。

例えば、次のようなエラーが表示されることがあります。

spawn latexmk ENOENT

または、ターミナルで次のように表示される場合があります。

latexmk: command not found

この場合は、LaTeXの実行ファイルがPATHから参照できているか確認します。

WindowsでPATHを確認する

Windowsでは、次のコマンドを利用できます。

where latexmk

例えば、次のようなパスが表示されれば認識されています。

C:\texlive\2026\bin\windows\latexmk.exe

macOS・LinuxでPATHを確認する

macOSやLinuxでは、次のコマンドを使用します。

which latexmk

実行ファイルのパスが表示されれば、PATHから認識されています。

VSCodeを再起動する

TeX Liveなどをインストールした直後は、VSCodeが古い環境変数を保持していることがあります。

その場合は、VSCodeを完全に終了してから再起動してください。

改善しない場合は、OSへの再ログインや再起動も試します。

なお、Windows版TeX Liveではインストーラーによって必要な環境設定が行われる場合があるため、必ず手動でPATH設定が必要というわけではありません。

latexmkが利用できるか確認する

LaTeX Workshopではlatexmkがよく使われる

LaTeX Workshopでは、標準的なビルド方法としてlatexmkを利用する設定が用意されています。

そのため、pdflatexは使えるのにlatexmkだけ使えない場合、LaTeX Workshopからのビルドに失敗する可能性があります。

次のコマンドを実行してください。

latexmk --version

正常にバージョン情報が表示されれば問題ありません。

MiKTeXではPerlも確認する

latexmkはPerlで動作するスクリプトです。

特にMiKTeXを利用している場合は、Perlが別途必要になることがあります。

次のコマンドで確認できます。

perl --version

ただし、TeX Liveなどでは利用者がPerlを個別に意識しなくてもlatexmkが動作する構成になっている場合があります。

そのため、LaTeX Workshopを使うために必ずPerlを手動インストールしなければならないという意味ではありません。

LaTeX Workshopがインストールされているか確認する

拡張機能を確認する

VSCodeでLaTeXを利用する場合は、一般的にLaTeX Workshopを使用します。

VSCodeで拡張機能画面を開きます。

WindowsやLinuxでは、次のショートカットが利用できます。

Ctrl + Shift + X

検索欄に次のように入力します。

LaTeX Workshop

インストールされていなければ、インストールしてください。

LaTeX Workshopからビルドする

LaTeXファイルを開いた状態でコマンドパレットを表示します。

Ctrl + Shift + P

次のコマンドを実行します。

LaTeX Workshop: Build LaTeX project

キーボードショートカットとしては、環境によってCtrl + Alt + Bが利用できます。

使用するLaTeXコンパイラを確認する

LaTeXには複数のコンパイラがある

LaTeXでは、文書によって適切なコンパイラが異なります。

代表的なものは次のとおりです。

  • pdfLaTeX
  • LuaLaTeX
  • XeLaTeX
  • pLaTeX
  • upLaTeX

文書が想定しているコンパイラと、実際に使用しているコンパイラが異なると、コンパイルエラーが発生することがあります。

日本語LaTeXでは文書クラスを確認する

日本語LaTeXでは、どの文書クラスやパッケージを利用しているかによって適切なコンパイラが変わります。

例えば、従来のpLaTeX・upLaTeX系の文書では、platexやuplatexを利用することがあります。

一方、LuaTeX-jaを利用した文書ではLuaLaTeXを使用します。

例えば、次のような文書クラスがあります。

\documentclass{ltjsarticle}

このような場合は、LuaLaTeXを利用する構成が一般的です。

重要なのは、「日本語LaTeXなら必ずこのコンパイラを使う」と決めるのではなく、使用している文書クラスやテンプレートが想定するエンジンを確認することです。

LaTeX Workshopのビルドレシピを確認する

レシピとは

LaTeX Workshopでは、LaTeXをどのような順序でビルドするかをrecipeと呼ばれる設定で管理します。

例えば、単純にlatexmkを実行する方法や、複数のコマンドを組み合わせる方法があります。

pdflatex
↓
bibtex
↓
pdflatex
↓
pdflatex

のような処理もレシピとして定義できます。

Build with recipeを試す

コマンドパレットから次を実行します。

LaTeX Workshop: Build with recipe

別のレシピを選択してコンパイルできるか確認してください。

使用するコンパイラとレシピが合っていない場合、ここを変更することで解決することがあります。

settings.jsonの設定を確認する

独自設定が原因になる場合がある

LaTeX Workshopでは、settings.jsonでビルド方法を変更できます。

代表的な設定には次のようなものがあります。

"latex-workshop.latex.tools"
"latex-workshop.latex.recipes"

独自にこれらを編集している場合、設定ミスによってビルドできなくなることがあります。

原因が分からない場合は、一度独自設定を無効にし、LaTeX Workshopの標準設定でビルドしてみると切り分けしやすくなります。

ルートファイルを正しく設定する

複数ファイル構成ではrootファイルが重要

LaTeXプロジェクトでは、複数の.texファイルを使用することがあります。

例えば、次のような構成です。

project/
├── main.tex
├── chapter1.tex
├── chapter2.tex
└── images/

この場合、main.texがメインファイルであるにもかかわらず、chapter1.texを単独でビルドすると失敗することがあります。

rootファイルを明示する

子ファイルの先頭に次のように記述できます。

% !TEX root = main.tex

子ファイルがサブディレクトリにある場合は、次のように指定します。

% !TEX root = ../main.tex

これにより、LaTeX Workshopがどのファイルをルートとしてビルドすればよいか判断しやすくなります。

LaTeXソース自体にエラーがないか確認する

基本文法のエラーを確認する

環境が正常でも、LaTeXソース自体にエラーがあればコンパイルできません。

例えば、次のような終了タグの不足があります。

\begin{document}

Hello

この場合は、次が必要です。

\end{document}

また、環境の閉じ忘れも典型的な原因です。

\begin{itemize}
\item A

この場合は次を追加します。

\end{itemize}

最小構成でテストする

原因を切り分ける場合は、次のような最小構成のLaTeXファイルを作成すると効果的です。

\documentclass{article}

\begin{document}

Hello, LaTeX!

\end{document}

例えば、test.texとして保存します。

pdfLaTeXを使用する場合は次を実行します。

latexmk -pdf test.tex

LuaLaTeXを使用する場合は次のようにします。

latexmk -lualatex test.tex

XeLaTeXを使用する場合は次のようにします。

latexmk -xelatex test.tex

最小構成で成功する場合、LaTeX環境そのものではなく、元の文書のソースコードやパッケージに原因がある可能性が高いです。

必要なLaTeXパッケージが不足していないか確認する

styファイルが見つからない場合

次のようなエラーが表示されることがあります。

LaTeX Error: File `xxxx.sty' not found.

これは、必要なLaTeXパッケージがインストールされていない場合によく発生します。

TeX LiveやMiKTeX側で必要なパッケージを追加してください。

特に最小構成のLaTeX環境を使用している場合は、必要なパッケージが含まれていないことがあります。

画像ファイルのパスを確認する

includegraphicsのパスミス

LaTeXで画像を読み込む場合、次のように記述します。

\includegraphics{images/sample.png}

指定した画像が存在しなければ、コンパイルに失敗する場合があります。

また、複数ファイル構成では、相対パスの基準や\graphicspathの設定にも注意が必要です。

単純に「必ず現在開いているファイル基準」とは限らないため、ルートファイルと画像パスの関係を確認してください。

BibTeX・Biberのエラーを確認する

参考文献を使っている場合

参考文献を使用している文書では、BibTeXやBiber関連のエラーが発生することがあります。

例えば、次のように設定している場合があります。

\usepackage[backend=biber]{biblatex}

この場合はBiberを使用します。

Biberが利用できるか確認するには、次を実行します。

biber --version

また、参考文献は1回LaTeXを実行するだけでは反映されない場合があります。

latexmkを使用すると、必要な処理を自動的に判断して実行しやすくなります。

補助ファイルの不整合を解消する

古い補助ファイルが原因になる場合がある

LaTeXをコンパイルすると、次のような補助ファイルが生成されます。

.aux
.log
.fls
.fdb_latexmk
.toc
.out
.synctex.gz

設定を大きく変更した場合や、途中でビルドに失敗した場合、古い補助ファイルの内容が原因で問題が起こることがあります。

LaTeX Workshopからクリーンアップする

コマンドパレットから次を実行します。

LaTeX Workshop: Clean up auxiliary files

その後、もう一度ビルドします。

latexmkから削除する場合は、次のコマンドも利用できます。

latexmk -C

ただし、latexmk -Cはlatexmkが管理対象としている生成ファイルを削除するコマンドであり、プロジェクト内のすべての生成物を無条件に削除するわけではありません。

ファイル名やフォルダー名を確認する

単純なパスで試す

現在のLaTeX環境ではUnicodeへの対応が進んでいるため、日本語のファイル名やフォルダー名を使用できる場合も多いです。

ただし、トラブルシューティング中は、特殊文字や長いパスを避けると原因を特定しやすくなります。

例えば、一時的に次のような場所へファイルを移動します。

C:\latex\test\

ASCII文字だけの短いパスで正常に動作するか確認すると、パスに起因する問題を切り分けやすくなります。

WSL・Remote SSH・Dev Containerを使用している場合

LaTeXは実行環境側に必要

VSCodeでは、WSLやRemote SSH、Dev Containerなどのリモート環境を利用できます。

例えば、Windows側にTeX Liveをインストールしていても、VSCodeをWSL環境で開いている場合、実際にLaTeXを実行するのはWSL側です。

そのため、WSL側でも次を確認する必要があります。

latexmk --version

Remote SSHやDev Containerでも同様です。

ホストOSにLaTeXが入っているだけでは不十分な場合があります。

エラーメッセージから原因を判断する

よくあるエラーと原因

代表的なエラーを整理すると次のようになります。

エラー主な原因
spawn latexmk ENOENTlatexmkが見つからない
latexmk: command not foundlatexmk未導入・PATHの問題
pdflatex: command not foundLaTeX本体未導入・PATHの問題
File xxx.sty not found必要なLaTeXパッケージ不足
Undefined control sequence未定義コマンド、スペルミス、パッケージ不足、エンジンの不一致など
Emergency stop重大なLaTeXエラー
Missing $ inserted数式モードや_・^などの記述ミス
Runaway argument{}などの対応ミス
参考文献が表示されないBibTeX・Biber・ビルド回数の問題
子ファイルだけ失敗するrootファイルの認識問題

LaTeX Workshopのログを確認する

出力パネルを見る

原因が分からない場合は、LaTeX Workshopのログを確認します。

VSCodeで次を開きます。

表示
↓
出力

出力パネルの対象をLaTeX Workshopに変更します。

ここでは、次のような情報を確認できます。

  • 使用したレシピ
  • 実行したコマンド
  • ビルド対象のファイル
  • コマンドが失敗した位置
  • エラーメッセージ

例えば、次のようにlatexmkを実行しようとしている場合があります。

command: latexmk

直後に、

ENOENT

が表示されている場合は、LaTeX文書の文法よりもlatexmkのPATHを疑うべきです。

ターミナルから直接コンパイルして切り分ける

LaTeX Workshopを介さず実行する

LaTeXのトラブルシューティングでは、VSCodeの統合ターミナルから直接コンパイルする方法が非常に有効です。

pdfLaTeXの場合は次を実行します。

latexmk -pdf main.tex

LuaLaTeXの場合は次です。

latexmk -lualatex main.tex

XeLaTeXの場合は次です。

latexmk -xelatex main.tex

ターミナルでも失敗する場合

ターミナルから直接実行しても失敗する場合は、主に次の原因が考えられます。

  • TeX環境
  • PATH
  • latexmk
  • LaTeXソース
  • 必要なパッケージ
  • 使用しているコンパイラ

この場合は、LaTeX Workshopだけの問題ではない可能性が高いです。

ターミナルでは成功する場合

ターミナルから直接コンパイルできるのに、LaTeX Workshopからだけ失敗する場合は、次を重点的に確認します。

  • LaTeX Workshopの設定
  • recipe
  • root file
  • working directory
  • VSCodeが認識しているPATH

VSCodeでLaTeXをコンパイルできないときの確認手順

1．LaTeX本体を確認する

まず次を実行します。

pdflatex --version

必要に応じて、使用するエンジンも確認します。

lualatex --version
xelatex --version

2．latexmkを確認する

次を実行します。

latexmk --version

3．VSCodeの統合ターミナルでも確認する

OS標準のターミナルでは動作しても、VSCode側からPATHを認識できていない場合があります。

そのため、必ずVSCodeの統合ターミナルでも確認してください。

4．最小構成のtexファイルを作る

次の内容をtest.texとして保存します。

\documentclass{article}

\begin{document}

Hello, LaTeX!

\end{document}

5．ターミナルからコンパイルする

pdfLaTeXなら次を実行します。

latexmk -pdf test.tex

6．LaTeX Workshopからビルドする

ターミナルでは成功したら、LaTeX Workshopからビルドします。

LaTeX Workshop: Build LaTeX project

7．別のレシピを試す

次を実行します。

LaTeX Workshop: Build with recipe

文書に適したレシピを選択してください。

8．LaTeX Workshopのログを確認する

最後に、VSCodeの出力パネルから詳細なエラーを確認します。

VSCodeでLaTeXをコンパイルできないときは順番に切り分けることが重要

VSCodeでLaTeXをコンパイルできない場合、最初に確認したいのは、LaTeX本体・latexmk・PATHの3点です。

LaTeX WorkshopをインストールしただけではLaTeX本体は利用できないため、TeX Live・MiKTeX・MacTeXなどのLaTeXディストリビューションも必要です。

まず、VSCodeの統合ターミナルで次を確認してください。

latexmk --version

さらに、使用するコンパイラに応じて次のようなコマンドも確認します。

pdflatex --version
lualatex --version
xelatex --version

その後、ターミナルから直接LaTeXをコンパイルしてみます。

ターミナルからは成功するのにLaTeX Workshopから失敗する場合は、LaTeX Workshopのレシピやrootファイル、設定を確認します。

ターミナルからも失敗する場合は、TeX環境、PATH、LaTeXソース、必要なパッケージなどを確認します。

このように、LaTeX本体、ターミナル、LaTeX Workshopの順番で切り分けていくと、VSCodeでLaTeXをコンパイルできない原因を効率的に特定できます。

以上、VSCodeでLaTeXをコンパイルできない原因と対処法についてでした。

最後までお読みいただき、ありがとうございました。

VSCode
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！

関連記事

  1. ホーム
  2. VSCode
  3. VSCodeでLaTeXをコンパイルできない原因と対処法
目次