Matplotlib Japanese Fonts

1.1.0 · active · verified Fri Apr 17

matplotlib-fontja is a Python library designed to easily enable Japanese character display in Matplotlib plots. It automatically detects available Japanese fonts on your system, updates Matplotlib's font cache, and configures `rcParams` to use them. The current version is 1.1.0, with updates typically focusing on compatibility and font detection improvements.

Common errors

```
UserWarning: No Japanese fonts found on your system. Please install one of the supported fonts for Japanese display.
```
cause The `matplotlib-fontja` library could not detect any suitable Japanese fonts installed on your operating system.

fix Install common Japanese fonts (e.g., Noto Sans CJK JP, Meiryo, Yu Gothic) on your OS. The specific installation method varies by OS (e.g., `apt install fonts-noto-cjk-extra` on Debian/Ubuntu, installing font files on Windows/macOS).
```
Japanese characters (e.g., こんにちは) appear as empty squares (☐) or generic boxes in Matplotlib plots.
```
cause Either no Japanese font is correctly configured for Matplotlib, or Matplotlib's font cache is outdated, or the system lacks Japanese fonts.

fix First, ensure Japanese fonts are installed on your OS. Then, make sure `matplotlib_fontja.set_font()` is called before `plt.show()`. If the problem persists, restart your Python environment and consider manually rebuilding the font cache: `import matplotlib.font_manager; matplotlib.font_manager._rebuild();`

Warnings

gotcha The library relies on Japanese fonts being installed at the operating system level. If no suitable fonts are found, `set_font()` will warn and Japanese characters may still appear as squares or be missing.
Fix: Ensure you have Japanese fonts (e.g., Noto Sans CJK, Yu Gothic, Meiryo) installed on your system. For Linux, refer to your distribution's font installation guides.
gotcha Although `matplotlib-fontja` attempts to rebuild Matplotlib's font cache, sometimes changes aren't immediately reflected, especially in long-running environments like Jupyter notebooks or IDEs.
Fix: If Japanese characters still appear as squares, try restarting your Python kernel or development environment. In rare cases, manually clearing the Matplotlib font cache might be necessary: `import matplotlib.font_manager; matplotlib.font_manager._rebuild();`
gotcha `set_font()` modifies global `matplotlib.rcParams` related to fonts. If you apply other `rcParams` changes after `set_font()`, they might override the Japanese font settings.
Fix: Call `matplotlib_fontja.set_font()` early in your script or notebook, ideally before any custom `rcParams` modifications that might conflict with font settings. If you need to override a specific font setting, do so after `set_font()`.

Install

pip install matplotlib-fontja Install stable version

Imports

matplotlib_fontja
wrong:
```
from matplotlib_fontja import set_font
```
correct:
```
import matplotlib_fontja
```
While 'from matplotlib_fontja import set_font' works, the recommended pattern is to import the module and call `matplotlib_fontja.set_font()` for clarity and to indicate it's a module-level configuration.

Quickstart

This quickstart demonstrates how to import `matplotlib-fontja`, apply its font configuration using `set_font()`, and then create a Matplotlib plot that correctly displays Japanese characters.

import matplotlib.pyplot as plt
import matplotlib_fontja

# Configure Matplotlib to use Japanese fonts
matplotlib_fontja.set_font()

# Create a simple plot with Japanese text
plt.figure(figsize=(8, 6))
plt.plot([1, 2, 3], [1, 4, 9])
plt.title('日本語タイトル (Japanese Title)')
plt.xlabel('X軸 (X-axis)')
plt.ylabel('Y軸 (Y-axis)')
plt.grid(True)
plt.show()

view raw JSON →