VSCodeでLaTeXがコンパイルできない問題を解決｜完全トラブルシューティングガイド

「VSCodeでLaTeXファイルをコンパイルしようとしてもエラーが出る…」
「LaTeX Workshopをインストールしたのに動かない」
「settings.jsonの設定方法がわからない」

Visual Studio Code（VSCode）でLaTeXを使おうとすると、環境構築やコンパイルでつまずくことがよくあります。特に、LaTeX Workshop拡張機能の設定は複雑で、初心者には難しいポイントです。

この記事では、VSCodeでLaTeXがコンパイルできない問題について、原因別に詳しい解決方法を解説します。

LaTeX環境の基本構成
1. 必要なコンポーネント
2. コンパイルの仕組み
エラー別トラブルシューティング
settings.jsonの完全な設定例
1. 方法1：.latexmkrcを使用（推奨）
2. 方法2：settings.jsonのみで完結
コンパイル方法
トラブルシューティングの基本手順
よくある質問
まとめ

LaTeX環境の基本構成

まず、VSCodeでLaTeXを使うために必要な要素を確認しましょう。

必要なコンポーネント

1. TeXディストリビューション

Windows: TeX Live または MiKTeX
Mac: MacTeX (TeX Liveベース)
Linux: TeX Live

2. VSCode本体

Microsoft公式サイトからダウンロード・インストール

3. LaTeX Workshop拡張機能

VSCodeの拡張機能マーケットプレイスからインストール
開発者: James Yu

4. Perl（latexmkを使う場合）

Windows: Strawberry Perlなど
Mac/Linux: 通常プリインストール済み

コンパイルの仕組み

LaTeX Workshopは、以下の流れでLaTeXファイルをコンパイルします。

Recipe（レシピ） を選択
Recipeで指定された Tool（ツール） を順番に実行
各Toolは実際のコマンド（platex、pdflatex、latexmkなど）を実行
PDFファイルが生成される

重要な設定ファイル：

settings.json: VSCodeの設定ファイル
.latexmkrc: latexmkの設定ファイル（オプション）

エラー別トラブルシューティング

エラー1：「Recipe terminated with fatal error: spawn latexmk ENOENT」

症状：

Recipe terminated with fatal error.
spawn latexmk ENOENT

原因：
latexmkコマンドが見つからない、またはPATHが通っていません。

解決方法1：PATHを確認

Windows：

VSCodeのターミナルを開く（Ctrl + `）
latexmkが実行できるか確認

latexmk -version

エラーが出る場合、環境変数PATHを確認

「システム環境変数の編集」を検索して開く
「環境変数」ボタンをクリック
「Path」を選択して「編集」
TeX Liveのbinフォルダを追加（例：C:\texlive\2023\bin\win32）

Mac/Linux：

ターミナルで以下を実行：

which latexmk

パスが表示されない場合、TeXディストリビューションが正しくインストールされていません。

解決方法2：フルパスを指定

settings.jsonで、latexmkのフルパスを指定します。

{
  "latex-workshop.latex.tools": [
    {
      "name": "latexmk",
      "command": "C:/texlive/2023/bin/win32/latexmk.exe",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-pdf",
        "%DOC%"
      ]
    }
  ]
}

解決方法3：VSCodeを再起動

環境変数を変更した後は、VSCodeを完全に再起動する必要があります。

エラー2：日本語LaTeXがコンパイルできない

症状：
英語のLaTeX文書はコンパイルできるが、日本語を含む文書がコンパイルできない。

原因：
LaTeX Workshopのデフォルト設定は欧文用（pdflatex）なので、日本語には対応していません。

解決方法1：.latexmkrcを使用（推奨）

ホームディレクトリに.latexmkrcファイルを作成します。

Windowsの場合：
C:\Users\USERNAME\.latexmkrc

Mac/Linuxの場合：
/home/USERNAME/.latexmkrc または ~/.latexmkrc

.latexmkrcの内容（uplatexの場合）：

#!/usr/bin/env perl

# LaTeX
$latex = 'uplatex %O -halt-on-error -interaction=nonstopmode -file-line-error -synctex=1 %S';

# BibTeX
$bibtex = 'upbibtex %O %B';
$biber = 'biber --bblencoding=utf8 -u -U --output_safechars %O %S';

# index
$makeindex = 'mendex %O -o %D %S';

# DVI / PDF
$dvipdf = 'dvipdfmx %O -o %D %S';

$max_repeat = 5;

# PDF生成モード（3 = DVI経由）
$pdf_mode = 3;

$pvc_view_file_via_temporary = 0;

settings.jsonの設定：

{
  "latex-workshop.latex.tools": [
    {
      "name": "latexmk(.latexmkrc)",
      "command": "latexmk",
      "args": [
        "-cd",
        "%DOCFILE%"
      ]
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "latexmk(.latexmkrc)",
      "tools": [
        "latexmk(.latexmkrc)"
      ]
    }
  ]
}

解決方法2：ptex2pdfを使用

.latexmkrcを使わない場合、settings.jsonに直接記述します。

{
  "latex-workshop.latex.tools": [
    {
      "name": "ptex2pdf",
      "command": "ptex2pdf",
      "args": [
        "-l",
        "-ot",
        "-kanji=utf8 -synctex=1 -interaction=nonstopmode -file-line-error",
        "%DOC%"
      ]
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "ptex2pdf",
      "tools": [
        "ptex2pdf"
      ]
    }
  ]
}

エラー3：「No pages of output」

症状：

Latexmk: No pages of output

原因：
LaTeXのコンパイル中にエラーが発生し、PDFが生成されませんでした。

解決方法：

1. LaTeXファイルの内容を確認

最小限のテストファイルで試してみます。

\documentclass{article}
\begin{document}
Hello World!
\end{document}

これでもコンパイルできない場合、TeXディストリビューションに問題があります。

2. ログファイルを確認

エラーの詳細は.logファイルに記録されています。

VSCodeで「View LaTeX compiler logs」を選択してログを確認してください。

3. コマンドラインでコンパイル

ターミナルで直接コンパイルして、エラーメッセージを確認します。

latexmk -pdf test.tex

エラー4：エラーが出てもビルドが止まらない

症状：
LaTeXファイルにエラーがあっても、コンパイルが延々と続く（左下のぐるぐるマークが回転し続ける）。

原因：
-interaction=nonstopmodeオプションにより、エラーが発生してもコンパイルが継続されます。

解決方法：

settings.jsonに-halt-on-errorオプションを追加します。

{
  "latex-workshop.latex.tools": [
    {
      "name": "latexmk",
      "command": "latexmk",
      "args": [
        "-synctex=1",
        "-halt-on-error",
        "-interaction=nonstopmode",
        "-file-line-error",
        "-pdf",
        "%DOC%"
      ]
    }
  ]
}

または、-interaction=nonstopmodeを-interaction=batchmodeに変更します。

強制停止のキーバインド設定：

Ctrl + Shift + Pでコマンドパレットを開く
「Preferences: Open Keyboard Shortcuts」を選択
「latex workshop kill」で検索
「LaTeX Workshop: Kill LaTeX compiler process」にキーバインドを割り当てる（例：Alt + X）

エラー5：「Incorrect type. Expected “array”」

症状：
settings.jsonを編集すると、このエラーが表示される。

Incorrect type. Expected "array".

原因：
JSON形式が間違っています。特に、latex-workshop.latex.toolsは配列（[]）である必要があります。

間違った例：

{
  "latex-workshop.latex.tools": {
    "name": "pdflatex",
    "command": "pdflatex"
  }
}

正しい例：

{
  "latex-workshop.latex.tools": [
    {
      "name": "pdflatex",
      "command": "pdflatex",
      "args": [
        "-synctex=1",
        "-interaction=nonstopmode",
        "-file-line-error",
        "%DOC%"
      ]
    }
  ]
}

エラー6：「Undefined control sequence」

症状：

! Undefined control sequence.
l.1 \documentclass

原因：
LaTeXコマンドが認識されていません。考えられる原因：

TeXディストリビューションが正しくインストールされていない
commandに間違ったコマンドを指定している（例：pdftexではなくpdflatex）

解決方法：

settings.jsonのcommandを確認します。

間違い：

{
  "name": "pdflatex",
  "command": "pdftex"
}

正しい：

{
  "name": "pdflatex",
  "command": "pdflatex"
}

エラー7：Recipeが表示されない

症状：
settings.jsonを開いても、LaTeX WorkshopのRecipeやToolsが表示されない。

原因：
VSCodeの設定システムでは、デフォルト設定は表示されません。

解決方法：

settings.jsonに自分で追記する必要があります。

手順：

Ctrl + ,で設定を開く
検索ボックスに「latex tools」と入力
「Latex-workshop > Latex: Tools」欄の「Edit in settings.json」をクリック
自動的にデフォルト設定が挿入される
必要に応じて編集

エラー8：OneDrive上のファイルがコンパイルできない

症状：
OneDrive内のLaTeXファイルがコンパイルできない。

原因：
OneDriveの同期機能が、コンパイル中のファイルアクセスと競合します。

解決方法：

LaTeXファイルをOneDrive外のローカルフォルダに移動
または、OneDriveの同期を一時停止してからコンパイル
または、-output-directoryオプションでOneDrive外に出力

{
  "latex-workshop.latex.outDir": "C:/temp/latex_output"
}

エラー9：MiKTeXでパッケージが見つからない

症状：

! LaTeX Error: File 'xxx.sty' not found.

原因：
MiKTeXの自動インストール機能が動作していないか、パッケージが存在しません。

解決方法：

1. MiKTeX Consoleでパッケージをインストール

MiKTeX Consoleを管理者として実行
「Packages」タブで必要なパッケージを検索
「Install」をクリック

2. 自動インストールを有効化

MiKTeX Console → Settings
「Always install missing packages on-the-fly」を選択

3. MiKTeXを更新

MiKTeX Console → Updates
「Check for updates」→「Update now」

エラー10：Perl not found

症状：

Perl not found

原因：
latexmkはPerlスクリプトなので、Perlが必要です。

解決方法：

Windows：

Strawberry Perlをインストール

https://strawberryperl.com/

環境変数PATHにPerlを追加
VSCodeを再起動

または、latexmkを使わないRecipeを使用：

{
  "latex-workshop.latex.recipes": [
    {
      "name": "pdflatex",
      "tools": [
        "pdflatex"
      ]
    }
  ]
}

settings.jsonの完全な設定例

以下は、日本語LaTeX（uplatex）用の完全な設定例です。

方法1：.latexmkrcを使用（推奨）

.latexmkrc（ホームディレクトリに配置）：

#!/usr/bin/env perl
$latex = 'uplatex %O -halt-on-error -interaction=nonstopmode -file-line-error -synctex=1 %S';
$bibtex = 'upbibtex %O %B';
$biber = 'biber --bblencoding=utf8 -u -U --output_safechars %O %S';
$makeindex = 'mendex %O -o %D %S';
$dvipdf = 'dvipdfmx %O -o %D %S';
$max_repeat = 5;
$pdf_mode = 3;
$pvc_view_file_via_temporary = 0;

settings.json：

{
  "latex-workshop.latex.tools": [
    {
      "name": "latexmk(.latexmkrc)",
      "command": "latexmk",
      "args": [
        "-cd",
        "%DOCFILE%"
      ]
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "latexmk(.latexmkrc)",
      "tools": [
        "latexmk(.latexmkrc)"
      ]
    }
  ],
  "latex-workshop.view.pdf.viewer": "tab",
  "latex-workshop.latex.autoBuild.run": "onFileChange",
  "latex-workshop.latex.autoClean.run": "onBuilt"
}

方法2：settings.jsonのみで完結

{
  "latex-workshop.latex.tools": [
    {
      "name": "uplatex",
      "command": "uplatex",
      "args": [
        "-synctex=1",
        "-halt-on-error",
        "-interaction=nonstopmode",
        "-file-line-error",
        "%DOC%"
      ]
    },
    {
      "name": "dvipdfmx",
      "command": "dvipdfmx",
      "args": [
        "%DOCFILE%"
      ]
    },
    {
      "name": "upbibtex",
      "command": "upbibtex",
      "args": [
        "%DOCFILE%"
      ]
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "uplatex -> dvipdfmx",
      "tools": [
        "uplatex",
        "dvipdfmx"
      ]
    },
    {
      "name": "uplatex -> bibtex -> uplatex*2 -> dvipdfmx",
      "tools": [
        "uplatex",
        "upbibtex",
        "uplatex",
        "uplatex",
        "dvipdfmx"
      ]
    }
  ],
  "latex-workshop.view.pdf.viewer": "tab",
  "latex-workshop.latex.autoBuild.run": "onFileChange",
  "latex-workshop.latex.autoClean.run": "onBuilt",
  "latex-workshop.latex.clean.fileTypes": [
    "*.aux",
    "*.bbl",
    "*.blg",
    "*.idx",
    "*.ind",
    "*.lof",
    "*.lot",
    "*.out",
    "*.toc",
    "*.synctex.gz"
  ]
}

コンパイル方法

自動コンパイル

settings.jsonで以下を設定すると、ファイル保存時に自動コンパイルされます。

{
  "latex-workshop.latex.autoBuild.run": "onFileChange"
}

手動コンパイル

方法1：ショートカットキー

Ctrl + Alt + B（Windows/Linux）
Cmd + Alt + B（Mac）

方法2：右上のビルドアイコン

右上の緑色の三角アイコンをクリック

方法3：コマンドパレット

Ctrl + Shift + Pでコマンドパレットを開く
「LaTeX Workshop: Build LaTeX project」を選択

Recipeの選択

複数のRecipeがある場合、選択して実行できます。

Ctrl + Shift + Pでコマンドパレットを開く
「LaTeX Workshop: Build with recipe」を選択
使用したいRecipeを選択

トラブルシューティングの基本手順

コンパイルできない場合、以下の手順で原因を特定します。

ステップ1：最小限のファイルでテスト

\documentclass{article}
\begin{document}
Hello World!
\end{document}

これがコンパイルできない場合、TeXディストリビューションに問題があります。

ステップ2：ターミナルで直接コンパイル

VSCodeのターミナルで直接コマンドを実行します。

pdflatex test.tex

または

latexmk -pdf test.tex

これで成功する場合、settings.jsonの設定に問題があります。

ステップ3：ログを確認

LaTeX Workshopのログ：

VSCode左下の「Output」タブを開く
ドロップダウンから「LaTeX Workshop」を選択
エラーメッセージを確認

LaTeXのログ：

.logファイルを開いて、最初のエラーメッセージを確認します。

ステップ4：設定をリセット

settings.jsonのLaTeX Workshop関連設定をすべて削除して、デフォルトに戻します。

ステップ5：拡張機能を再インストール

LaTeX Workshop拡張機能をアンインストール
VSCodeを再起動
LaTeX Workshopを再インストール

よくある質問

Q1. TeX LiveとMiKTeXのどちらを使うべきですか？

A: 個人的な好みですが、以下のような違いがあります。

TeX Live: フルインストールすると約7GB、すべてのパッケージが含まれる、アップデートが年1回
MiKTeX: 最小インストールは小さい、必要なパッケージを自動インストール、随時アップデート可能

初心者にはTeX Liveのフルインストールがおすすめです（パッケージ不足のエラーが少ない）。

Q2. platexとuplatexの違いは何ですか？

platex: 古い日本語LaTeX、EUC-JPエンコーディング
uplatex: 新しい日本語LaTeX、UTF-8対応、Unicode対応

現在はuplatexの使用を推奨します。

Q3. PDFが自動で開きません

A: settings.jsonで以下を確認してください。

{
  "latex-workshop.view.pdf.viewer": "tab"
}

または、手動でPDFを開く：

Ctrl + Alt + V（Windows/Linux）
Cmd + Alt + V（Mac）

Q4. エラーメッセージが日本語で表示されません

A: VSCodeの表示言語は変更できますが、LaTeXコンパイラのエラーメッセージは通常英語です。これは正常な動作です。

Q5. 参考文献（BibTeX）が反映されません

A: 参考文献を含むドキュメントは、複数回のコンパイルが必要です。

以下のRecipeを使用してください：

{
  "name": "uplatex -> bibtex -> uplatex*2 -> dvipdfmx",
  "tools": [
    "uplatex",
    "upbibtex",
    "uplatex",
    "uplatex",
    "dvipdfmx"
  ]
}

まとめ

VSCodeでLaTeXがコンパイルできない問題について解説しました。

重要なポイントをおさらいします：

環境構築：

TeXディストリビューション、VSCode、LaTeX Workshopの3つが必要
PATHが正しく設定されているか確認
Perlのインストールが必要な場合がある

日本語LaTeX：

デフォルト設定では日本語に対応していない
.latexmkrcを使用するのが最も簡単
uplatexの使用を推奨

settings.json：

latex-workshop.latex.tools: 実際のコマンドを定義
latex-workshop.latex.recipes: Toolsの実行順序を定義
JSON形式のエラーに注意（特に配列[]）

トラブルシューティング：

最小限のファイルでテスト
ターミナルで直接コンパイル
ログファイルを確認
-halt-on-errorオプションでエラー時に停止

よくあるエラー：

spawn latexmk ENOENT: PATHが通っていない
日本語が表示されない: Recipeが欧文用
エラーで止まらない: -halt-on-errorを追加
Incorrect type: JSON形式が間違っている

LaTeX環境の構築は最初は難しいですが、一度正しく設定すれば快適に使えるようになります。

この記事を参考に、VSCodeでのLaTeX環境を構築してください！

LaTeX環境の基本構成

必要なコンポーネント

コンパイルの仕組み

エラー別トラブルシューティング

エラー1：「Recipe terminated with fatal error: spawn latexmk ENOENT」

エラー2：日本語LaTeXがコンパイルできない

エラー3：「No pages of output」

エラー4：エラーが出てもビルドが止まらない

エラー5：「Incorrect type. Expected “array”」

エラー6：「Undefined control sequence」

エラー7：Recipeが表示されない

エラー8：OneDrive上のファイルがコンパイルできない

エラー9：MiKTeXでパッケージが見つからない

エラー10：Perl not found

settings.jsonの完全な設定例

方法1：.latexmkrcを使用（推奨）

方法2：settings.jsonのみで完結

コンパイル方法

自動コンパイル

手動コンパイル

Recipeの選択

トラブルシューティングの基本手順

ステップ1：最小限のファイルでテスト

ステップ2：ターミナルで直接コンパイル

ステップ3：ログを確認

ステップ4：設定をリセット

ステップ5：拡張機能を再インストール

よくある質問

Q1. TeX LiveとMiKTeXのどちらを使うべきですか？

Q2. platexとuplatexの違いは何ですか？

Q3. PDFが自動で開きません

Q4. エラーメッセージが日本語で表示されません

Q5. 参考文献（BibTeX）が反映されません

まとめ

Youtube

カテゴリー別人気記事

コメント