fugashi

library1.5.2pypypi✓ verified 23d ago

Fugashi is a Cython wrapper for MeCab, providing fast and Pythonic Japanese tokenization and morphological analysis. It offers pre-built wheels for common platforms and simplifies dictionary installation, primarily recommending UniDic. The library is actively maintained and currently at version 1.5.2.

ai-ml data

pip install fugashi

github ↗package ↗

INSTALL

IMPORT

SIG · FUGASHI

fugashi

ai-mlpythonv1.5.2

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

2/3 runs

py 3.11

✕ build_error

2/3 runs

py 3.12

✕ build_error

2/3 runs

py 3.13

✕ build_error

2/3 runs

py 3.9

✕ build_error

2/3 runs

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Tagger

✓ from fugashi import Tagger

GenericTagger

✓ from fugashi import GenericTagger

Use when working with custom or non-UniDic dictionaries.

create_feature_wrapper

✓ from fugashi import create_feature_wrapper

Helper for creating named tuple wrappers for custom dictionary features.

Initializes a `Tagger` for Japanese text, demonstrating basic tokenization (wakati) and accessing morphological features like lemma and part-of-speech using UniDic features. The `tagger()` call directly yields `Word` objects for convenient iteration and attribute access.

from fugashi import Tagger # Initialize Tagger with '-Owakati' for whitespace-separated output tagger = Tagger('-Owakati') text = "麩菓子は、麩を主材料とした日本の菓子。" # Get whitespace-separated tokens wakati_output = tagger.parse(text) print(f"Wakati: {wakati_output}") # Iterate through words to get detailed features (UniDic assumed by default) print("\nDetailed analysis:") for word in tagger(text): print(f"Surface: {word.surface}\tLemma: {word.feature.lemma}\tPOS: {word.pos}") # Example with GenericTagger and custom features (if not using UniDic or need specific fields) # from fugashi import GenericTagger, create_feature_wrapper # CustomFeatures = create_feature_wrapper('CustomFeatures', 'alpha beta gamma') # custom_tagger = GenericTagger(wrapper=CustomFeatures) # print("\nCustom Tagger example:") # for word in custom_tagger.parseToNodeList("テスト"): # Example, requires a configured custom dictionary # print(f"Surface: {word.surface}\tAlpha: {word.feature.alpha}")

fugashi --version

Debug

Known issues

breakingSupport for Python 3.6 and earlier versions was dropped in fugashi v1.2.0. Users on older Python versions must upgrade or use fugashi v1.1.2 or earlier.

fix

Upgrade to Python 3.9+.

affects: <1.2.0

gotchaFugashi requires a MeCab dictionary to function. Forgetting to install one (e.g., `unidic-lite` or `unidic`) is a common error and will lead to initialization failures.

fix

Install a dictionary via `pip install 'fugashi[unidic-lite]'` or `pip install 'fugashi[unidic]' && python -m unidic download`.

affects: All

gotchaOn platforms where pre-built wheels are not available (e.g., musl-based Linux distros like Alpine, PowerPC, or Windows 32-bit), MeCab itself must be installed from source *before* installing fugashi.

fix

Manually install MeCab from source for your specific platform before `pip install fugashi`. Consult MeCab documentation for details.

affects: All

deprecatedEarlier versions of MeCab wrappers (like `mecab-python3`) often returned a linked-list structure for `parseToNode`. Fugashi adopted a more Pythonic approach by returning a Python list of nodes, which is a significant API improvement for usability.

fix

Ensure you are using `fugashi` for its Pythonic list-based node access, which simplifies processing with list comprehensions and other idioms.

affects: Older MeCab wrappers (<fugashi v1.0)

Errors

Common errors & fixes

ImportError: DLL load failed while importing fugashi: The specified module could not be found.

This error typically occurs on Windows systems when the necessary underlying MeCab DLLs are not found or are not accessible in the Python environment's PATH, often due to issues with the installation or virtual environments.

fix

Ensure you are using a Python virtual environment and reinstall `fugashi` there. If the problem persists, it may be related to the Windows installation of Python (e.g., from the Windows Store), and using a standalone Python installation is recommended.

RuntimeError: Failed initializing MeCab. Please see the README for possible solutions:

This error indicates that the `fugashi` Tagger object could not initialize MeCab, most commonly because a required Japanese dictionary (like UniDic) is not installed or MeCab itself is not properly set up in the environment.

fix

Install a dictionary for `fugashi`. For UniDic-lite (recommended for quick start), run: `pip install 'fugashi[unidic-lite]'`. For the full UniDic, run: `pip install 'fugashi[unidic]'` followed by `python -m unidic download`. If you are on a platform without pre-built wheels, ensure MeCab is installed from source first.

ModuleNotFoundError: No module named 'fugashi.fugashi'

This specific ModuleNotFoundError indicates that the internal C-extension module `fugashi.fugashi` could not be found, which can happen in specific environments like Docker due to caching issues, incorrect PATH settings, or a corrupted installation.

fix

Reinstall `fugashi` using `--force-reinstall` and `--no-warn-script-location` within your environment (e.g., Docker container): `pip install fugashi --force-reinstall --no-warn-script-location`.

RuntimeError: Could not configure working env. Have you installed MeCab?

This error occurs when `fugashi` is being built from source (e.g., on platforms without pre-built wheels like Alpine Linux) and the MeCab C++ library is not found in the system. `fugashi` itself does not install MeCab.

fix

Install the MeCab C++ library on your system before attempting to install `fugashi`. For example, on Debian/Ubuntu: `sudo apt-get install mecab libmecab-dev mecab-ipadic-utf8` (or an appropriate UniDic package if available through your system's package manager).

Upgrade

Version history

1.5.2latest on PyPI · released Oct 24, 2025

Audit

Dependencies

MeCabrequiredCore tokenizer engine. Wheels include binaries, but manual installation from source is needed on unsupported platforms.

UniDicrequiredRecommended Japanese dictionary for morphological analysis. Required for most use cases, available as `unidic-lite` (lightweight) or `unidic` (full).

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sponsors/polm ↗

packagehttps://pypi.org/project/fugashi/ ↗