LaTeX で画像が取り込めない原因 5 選

<!-- # LaTeX で画像が取り込めない原因 5 選 -->

LaTeX で画像を取り込むには graphics あるいは graphicx パッケージを利用します。
しかし、「パッケージを読み込んで `\includegraphics` すれば良いや」と思ってやってみても、なぜか上手くいかないことがあります。

本記事では、よくある画像が取り込めない原因はこれだろうというものを 5 つ選び、その解決法方法を紹介します。

:::note info
本記事では graphics パッケージと表記しますが、graphicx パッケージであっても同じです。
:::

## タイプミス

ファイル名あるいはパス名を間違うことは、もっとも単純でよくあるミスです。ファイル名やパス名が間違っていれば、当然ながら画像は取り込められません。

他にも、拡張子を間違っていることもあります。特に、<samp>.pdf</samp> と <samp>.png</samp> を間違えやすいです。（個人的観測）

あるいは、パッケージ名 (graphics・graphicx) やコマンド名 (`\includegraphics`) を間違えている可能性もあります。

この手のミスのときは、“Undefined control sequence.” がエラーメッセージとして表示されます。このエラーのときはパッケージ名やコマンド名を間違えている可能性を検討しましょう。

## ドライバオプションの指定・未指定

初心者が躓きやすい点で、かつ独自の謎ノウハウが展開されやすいところです。

主要な日本語を扱う LaTeX は LuaLaTeX と (u)pLaTeX です。これらのドライバオプション指定の必要不要は以下の通りです。

| LaTeX エンジン | ドライバオプションの有無 |
| :------------: | :----------------------: |
|    LuaLaTeX    |           不要           |
|   (u)pLaTeX    |  必要（`dvipdfmx` 等）   |

LuaLaTeX では `dvipdfmx` 等のドライバオプションの指定は不要です。と言うより、指定することで画像を上手く扱えなくなります。

一方で、upLaTeX・pLaTeX では必須です。必ず指定しましょう。指定方法は `\documentclass` のオプションで以下のようにします。[^dvipdfmx]

[^dvipdfmx]: `dvipdfmx` オプションを追加するのは upLaTeX で出力された DVI を PDF に変換するために dvipdfmx を利用するからです。
    もしも DVI から PostScript に変換する場合は dvips を使用するため、`dvipdfmx` の代わりに `dvips` オプションを課します。

```latex
\documentclass[dvipdfmx]{jsarticle}
```

`\usepackage{graphics}` でドライバオプションを指定することも出来ますが、graphics パッケージ以外にも color パッケージ等のドライバに依存したパッケージが存在します。
もしも `\usepackage` で `dvipdfmx` オプション等を課す場合、これらすべてにも課す必要があり面倒です。

また、暗に内部で graphics パッケージや color パッケージを使っている場合もあり、これらすべてを把握するのは現実的でありません。[^dvi-dependency]

[^dvi-dependency]: ドライバに依存したパッケージは数多くあり、それらは一般にリスト化されていません。graphics、(x)color の他にも、hyperref や TikZ、geometry、またそれらを読み込むパッケージ（chemfig や tcolorbox、siunitx 等）も暗に DVI ドライバに依存しています。

    それらを完全に把握するのは骨の折れる作業であり、把握しようとすることは無駄骨と言っても過言ではないでしょう。

そのため、`\documentclass` のオプションで指定することをお勧めします。[^dvipdfmx-option]

[^dvipdfmx-option]: graphics パッケージと color パッケージの併用をしているときに、`dvipdfmx` オプション付きの graphics と `dvipdfmx` オプション無しの color パッケージをこの順で読み込むと、PNG 画像等が取り込めません。

    解決方法として、両方にオプションを付けるとか読み込み順序の問題だとか言われますが、`\documentclass` のオプションで指定すれば解決する話です。

    加えて、この問題は暗に内部でこれらのパッケージを読み込むパッケージにも波及する問題です。読み込み順序等で解消するのはバッドノウハウを増やすだけになるでしょう。（[参考][zr_tex8r-442b75b452b11bee8049]）

[zr_tex8r-442b75b452b11bee8049]: https://qiita.com/zr_tex8r/items/442b75b452b11bee8049 "LaTeX: graphicx と color の危険な関係 #LaTeX - Qiita"

ただし、ドライバをグローバルに指定していると不都合な場合（いつか分からないけれど）、graphics と color の両方に `dvipdfmx` オプションを課すようにしてください。（[参考][texwiki-tikz]）

[texwiki-tikz]: https://texwiki.texjp.org/?TikZ#e634a5d8 "TikZ - TeX Wiki"

## ドラフトモード

画像が取り込まれるはずなのに取り込まれない原因の 1 つです。

graphics パッケージは `draft` オプションによって画像を文書内に持ち込まずに、bouding box だけを表示するようにできます。これは、文章の草稿段階で利用される LaTeX のタイプセットを高速化するテクニックの 1 つです。

この `draft` オプションを有効にしたままにしているがために、画像が表示されない（と勘違いする）ことがあります。

この問題は、`draft` オプションを消して `final` オプションを有効にすれば解消します。

----------

Overleaf を使っている場合は Compile モードに注意が必要です。

Overleaf の Recompile メニューの Compile モードには Normal と [Final \[draft\]][overleaf-draft] があります。これを指定している場合、`draft` オプションと同じ効果を得ます。
画像が表示されない場合には、Compile モードがどうなっているかも確認してください。

[overleaf-draft]: https://www.overleaf.com/learn/how-to/Fixing_and_preventing_compile_timeouts#second_images "§ Step 2: Try compiling in Fast [draft] mode | Fixing and preventing compile timeouts - Overleaf, Online LaTeX Editor"

----------

草稿版と完成版の違いを明瞭にするテクニックについては、以下の記事の [§ 草稿版と完成版の切替][wtsnjp-20231223-draft] が参考になります。

[wtsnjp-20231223-draft]: https://blog.wtsnjp.com/2023/12/23/lengthy-writing/#%E8%8D%89%E7%A8%BF%E7%89%88%E3%81%A8%E5%AE%8C%E6%88%90%E7%89%88%E3%81%AE%E5%88%87%E6%9B%BF "LaTeXで大規模な文書も幸せに作りたい | ラング・ラグー"

https://blog.wtsnjp.com/2023/12/23/lengthy-writing/

## サブファイルにおける画像ファイルの相対パス

大型の文書を書く場合、LaTeX 標準の `\input` や `\include` を用いて文章を分割することがあります。

例えば、以下のようなディレクトリ構成になっているとします。

```directory
.
├─ main.tex
├─ sub/
│	├─ sub1.tex
│	⋮
└─ image/
	└─ sample.pdf
```

すると、main.tex と sub1.tex で image/sample.pdf の相対パスが異なることになります。

```latex
% main.tex
\documentclass{article}
\usepackage{graphics}
\begin{document}

% この画像は表示される
\includegraphics{./image/sample.pdf}

% この画像は表示されない
\input{./sub/sub1.tex}

\end{document}
```

```latex
% sub1.tex
\includegraphics{../image/sample.pdf}
% 相対パスは sub1.tex から見たものになっている
```

このようにしてタイプセットすると、sub1.tex 側の画像が表示されません。
これは、main.tex からパスを追っているために、指定された画像を見つけられなかったことが原因です。

そのため、画像が含まれたサブファイルを `\input` や `\include` で統合する場合は、以下のように main.tex から見た相対パスに変更します。

```diff_te_x
% sub1.tex
- \includegraphics{../image/sample.pdf}
- % 相対パスは sub1.tex から見たものになっている
+ \includegraphics{./image/sample.pdf}
+ % 相対パスは main.tex から見たものにする
```

----------

ところで、TeX ファイルを分割・統合するパッケージとして有名な subfiles パッケージの場合はこのような対応を採る必要はありません。

それぞれのサブファイルから見た相対パスを指定していても、メインファイルでは良しなに処理してくれます。

## `\graphicspath` の不備

graphics パッケージでは、`\graphicspath` によって画像フォルダを指定することが出来ます。
TeX ファイルを分割している際にも有用なテクニックです。

このコマンドによってパスを指定する場合、それぞれのパスは波括弧で囲われている必要があります。これはパスが 1 つの場合も例外ではありません。

例えば、以下のようなディレクトリ構成の場合を考えます。

```directory
.
├─ main.tex
├─ pdf/
│	└─ image.pdf
└─ png/
	└─ image.png
```

このとき、<samp>pdf/</samp> と <samp>png/</samp> を `\graphicspath` で指定するには、以下のようにします。

```latex
\graphicspath{{pdf/}{png/}}
```

例え <samp>pdf/</samp> だけを指定する場合でも波括弧は必要です。

```latex
\graphicspath{{pdf/}}
```

少々奇妙な感じもしますが、波括弧を忘れないようにしましょう。

## 余談

LaTeX で画像が取り込めない原因を 5 つ紹介してみました。おそらくこれらが原因の大半を占めているだろうと思います。（他に、もっとよくある原因があるかしら）

特に 2 つ目の `dvipdfmx` オプションに関してはいつでも注意しましょう。

(u)pLaTeX を利用する際の `dvipdfmx` オプションの不備は、LaTeX 初心者にとって少々厄介な問題になりがちです。`\documentclass` のオプションに追加することを忘れないでください。

一方で、LuaLaTeX では `dvipdfmx` オプションは不要です。LuaLaTeX に移行した際によくやるミスなので、これも注意が必要です。

----------

以降では、頻繁に発生するわけではないものの画像が取り込めない原因やちょっと困ったことになりうる原因を紹介します。

### bounding box が取得できない

bounding box は画像のサイズを表す値です。

https://texwiki.texjp.org/?%E3%83%90%E3%82%A6%E3%83%B3%E3%83%87%E3%82%A3%E3%83%B3%E3%82%B0%E3%83%9C%E3%83%83%E3%82%AF%E3%82%B9

この値は pdfLaTeX や LuaLaTeX では内部で取得しますが、dvipdfmx を利用する (u)pLaTeX では外部の extractbb を実行して bounding box を取得します。

通常、extractbb は (u)pLaTeX を実行する裏で実行されますが、これが上手く実行されないことがあるようです。
このとき、“Cannot determine size of graphic in filename.xbb” のようなエラーメッセージを取得します。

例えば、7 月頃に TeX Live 2024 の extractbb が Lua スクリプトになったことが影響して bounding box が取得できないエラーが発生していました。（[参考 1][okumuralab-3791]、[参考 2][texwiki-extractbb]）

[okumuralab-3791]: https://okumuralab.org/tex/mod/forum/discuss.php?d=3791 "QA: extractbb が変わったようですが | TeX Forum"
[texwiki-extractbb]: https://texwiki.texjp.org/?dvipdfmx#k882a214 "extractbb などの名前でシンボリックリンクを作成する → extractbb は extractbb.lua に置き換えられました | dvipdfmx - TeX Wiki"

----------

(u)pLaTeX の実行内で extractbb による bounding box の取得が上手くいかない場合は、対処療法的な方法ではありますが、画像ファイルのあるディレクトリに <samp>.xbb</samp> ファイルを配置します。このファイルは extractbb から出力されます。

```console
$ extractbb filename.png
```

あるいは、`extractbb -O filename.png` としてターミナル内に結果を表示させ、`BoundingBox` の値を `\includegraphics` の `bb` オプションに与えても良いでしょう。（`HiResBoudingBox` でも良い）

### 画像ファイルの不備

まれに画像ファイルを出力したり別の形式に変換した際に、画像ファイルそのものに欠陥があるファイルを生成することがあります。

これが原因で LaTeX の処理フロー等に問題が無くても画像が表示されないことがあるようです。

### `\includegrapihcs` のオプション

graphic**s** パッケージと graphic**x** パッケージでは、コマンドのオプションの採り方が異なります。

挿入する画像は `width` オプション等を利用して画像サイズを指定することが多いですが、このオプションは graphic**s** パッケージでは利用**できません**。
たまに graphics で良いやと思って適当に `\usepackage` すると戸惑うことがあります。

:::note info
graphic**x** パッケージを使いましょう。
:::

### ファイル名

ファイル名には以下の 13 の文字は使えません。[^win-filename]

[^win-filename]: Windows 以外では使える文字も含まれていますが、互換を考えると使うのは避けるべきでしょう。

- OS でファイル名に使えない文字
    ```
    \ / : * ? " < > |
    ```
- LaTeX のファイル名に使えない文字
    ```
    # % { }
    ```

ベターなファイル名は、半角英数と `-`、`_` で構成したものです。

:::note info
ファイル名は半角英数と `-`、`_` で構成しましょう。
:::

しかしながら、近年の LaTeX では上のような構成のファイル名以外であっても上手く処理して取り込むことができるようになっています。

#### ドット、スペース、日本語

画像のファイル名（拡張子左の `.` とは別）にドット (`.`) やスペース (<code>&nbsp;</code>) が含まれる場合、上手く画像を読み込めませんでした。

これの最も簡単な解決方法は、ファイル名にドットやスペースを含めないことですが、grffile パッケージを使うことでも解決します。（2019 年くらいまではファイル名を波括弧で囲う裏技があったようです）

しかしながら、近年の LaTeX ではドットやスペースを含むファイル名であっても上手く処理するようになっています。

- <details> <summary>Improving file name handling in pdfTeX (Issue 30, 2019-10-01)</summary>

    A related change is that file names used as part of `\input`, `\includegraphics`, etc., commands can now contain any Unicode characters allowed by the file system in use, including spaces. In this case, even characters that can’t be typeset (due to lack of font support) can be used. </details>

- <details> <summary>Files with multiple parts (Issue 32, 2020-10-01)</summary>

    Sometimes one has a graphics file, say, <samp>file.svg</samp>, and converts it to another format to include it in LaTeX and ends up with a file named <samp>file.svg.png</samp>. In previous releases, if the user did `\includegraphics{file.svg}`, an error would be raised and the graphics inclusion would fail due to the unknown .svg extension. The graphics package now checks if the given extension is known, and if it doesn’t, it tries appending the known extensions until it finds a graphics file with a valid extension, otherwise it falls back to the file as requested. </details>

- <details> <summary>File names with spaces, multiple dots or utf-8 characters (Issue 33, 2021-06-01)</summary>

    In one of the recent LaTeX releases we improved the interface for specifying file names so that they can now safely contain spaces (as is common these days), more than one dot character, and also utf-8 characters outside the ascii range. In the past this was only possible by applying a special syntax in the case of spaces, while file names with several dots often failed, as did most utf-8 characters. </details>

ただし、(u)pLaTeX ではスペースを含むファイルを処理できません。[^extractbb-space]

[^extractbb-space]: extractbb が実行時にファイル名のスペースを区切り文字として認識するためです。
これを踏まえると、`\includegraphics` に `bb` オプションで bounding box を手動で与えてしまえば extractbb を実行せずに済むので、エラー無く実行できます。

加えて、pLaTeX では ` 表 ` 等の文字を含むファイル名を扱えません。これは、Shift_JIS において一部が `\` と解釈される文字です。（いわゆる文字化けであり、ダメ文字とも呼ばれる）
このような文字は代表的に以下のようなものがあります。（[参考][tohoho-code]）

[tohoho-code]: https://www.tohoho-web.com/ex/draft/code.htm "シフトJIS漢字コード表 - とほほのWWW入門"

```
Ⅸ ソ 予 十 構 申 表 貼
```

このような場合もあるため、ドットやスペース、漢字を含まない半角英数のみ方が賢明な場合もあります。画像を取り込めるとは言え、これらの文字は避けておくべきでしょう。

#### 大文字・小文字

`\includegraphics` でファイル名を指定するとき、ファイルの大文字・小文字は気にしなくても大丈夫な可能性があります。

本来、ファイル名は case sensitive であり正確に表記するべきですが、2018 年以降の TeX Live では指定されたファイル名の捜索が失敗すると case insensitive にフォールバックして捜索し直します。

この機能は kpathsea の `texmf_casefold_search` によって制御され、texmf.cfm あるいは環境変数で `0` にするとフォールバックが無効になります。（§ 9.1.15 2018, [The TeX Live Guide — 2024][texlive-en-9115]、より詳細には § 5.4 Casefolding search, [Kpathsea library][kpathsea]）

[texlive-en-9115]: https://www.tug.org/texlive/doc/texlive-en/texlive-en.html#x1-870009.1.15 "§ 9.1.15 2018 | The TeX Live Guide—2024"
[kpathsea]: https://ctan.org/pkg/kpathsea "CTAN: Package kpathsea"

しかしながら、ファイルを自分の実行環境とは異なる外部に渡したりする際には case insensitive になっていないと問題になる可能性があるため、あまりこのフォールバックを当てにしない方が良いでしょう。

<!-- ### 対応しない画像形式

graphics パッケージが対応する画像形式は以下の通りです。

- PDF
- PNG
- JPEG
- TIFF
- EPS

これ以外の画像形式は受け付けません。

そのため、SVG 形式の画像を埋め込もうとしても、エラーになってしまいます。素直に対応する画像形式へ変換することをお勧めします。

もしも SVG のまま埋め込みたい場合は、svg パッケージと Inkscape・ImageMagick を使いましょう。（ただし、この方法には LaTeX の `--shell-escape` が必要です）
-->

<!-- ### 追記

ドライバオプションに関する指摘 (https://x.com/zr_tex8r/status/1854723889915658642) を受けて、「dvipdfmx オプションの指定・未指定」節の書き方を修正しました。
-->