natto-py

library1.0.1pypypi✓ verified 22d ago

natto-py is a Python package that provides a Foreign Function Interface (FFI) binding to MeCab, the part-of-speech and morphological analyzer for the Japanese language. It allows Python applications to leverage MeCab's capabilities without requiring SWIG or a C compiler for installation. The current version is 1.0.1, and the library is actively maintained with an irregular release cadence.

data ai-ml serialization

pip install natto-py

github ↗package ↗

INSTALL

IMPORT

SIG · NATTO-PY

natto-py

datapythonv1.0.1

Install

2.8s avg

Import

44ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.1 · 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

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.048s · 20.9MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.8s · import 0.040s · 21MB

19MB installed

● package 19MB

Code

Verified usage

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

MeCab

✓ from natto import MeCab

MeCabNode

✓ from natto.mecab import MeCabNode

While MeCabNode instances are often yielded by MeCab.parse(as_nodes=True), direct import is also possible.

This quickstart demonstrates how to initialize `natto-py` with MeCab and perform both string-based and node-based parsing. The `with` statement is used for proper resource management, and MeCab options are set to obtain detailed morphological features for each node.

import os from natto import MeCab # Optional: Set MeCab path and charset if auto-detection fails # os.environ['MECAB_PATH'] = os.environ.get('MECAB_PATH', '/usr/local/lib/libmecab.so') # os.environ['MECAB_CHARSET'] = os.environ.get('MECAB_CHARSET', 'utf8') # Instantiate MeCab with recommended options for detailed parsing # -F: node-format for features, -U: unk-format for unknown words with MeCab(r'-F%m,%f[0],%f[1],%f[2],%f[3],%f[4],%f[5],%f[6],%f[7],%f[8]\n -U?,?,?,?,?,?,?,?,?,?\n') as nm: text = 'これは日本語のテキストです。' print(f"Parsed text (string output):\n{nm.parse(text)}\n") print("Parsed text (node output with features):") for n in nm.parse(text, as_nodes=True): if not n.is_eos(): # Ignore end-of-sentence nodes print(f'Surface: {n.surface}, Feature: {n.feature}, Cost: {n.cost}')

Debug

Known issues

breakingVersion 1.0.0 of natto-py formally dropped support for Python 2.x. Users who still require Python 2 compatibility must use `natto-py==0.9.2`.

fix

Upgrade to Python 3.7+ or pin `natto-py==0.9.2` for Python 2 projects.

affects: >=1.0.0

gotchanatto-py requires a pre-installed MeCab library (v0.996+) and a system dictionary (e.g., IPA, Unidic) on the operating system. These are not bundled. If natto-py cannot automatically locate MeCab, you may need to set the `MECAB_PATH` and `MECAB_CHARSET` environment variables.

fix

Ensure MeCab and a system dictionary are installed and accessible on your system's PATH, or explicitly set `os.environ['MECAB_PATH']` and `os.environ['MECAB_CHARSET']` in your Python code before importing `natto`.

affects: All versions

gotchaFor robust applications, it is highly recommended to instantiate `MeCab` using a Python `with` statement (e.g., `with MeCab() as nm:`). This ensures that MeCab's internal resources are properly cleaned up when the object goes out of scope, preventing potential memory leaks or crashes.

fix

Wrap `MeCab` instantiation in a `with` statement: `with MeCab(...) as nm:`.

affects: All versions

gotchaFor detailed morphological analysis, prefer parsing with `as_nodes=True` and customizing MeCab's output format using the `-F` (node-format) and `-U` (unknown-format) options during `MeCab` instantiation. This provides structured `MeCabNode` objects with rich features, avoiding brittle manual string parsing.

fix

Pass formatting options like `r'-F%m,%f[0],%f[1]
 -U?,?,?
'` to the `MeCab` constructor and iterate over `MeCabNode` instances using `nm.parse(text, as_nodes=True)`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'natto'

The 'natto-py' package has not been installed in your Python environment or the import statement is incorrect.

fix

Ensure the package is installed using pip: `pip install natto-py`

natto.api.MeCabError: MECAB_NBEST request type is not set

This error often occurs when specific MeCab output formatting options (e.g., `-F%f[8]`) are used with an incompatible MeCab version or an unsupported configuration for n-best parsing.

fix

Review your MeCab instantiation parameters, particularly the `-F` (node-format) and `-U` (unknown-format) options. Ensure your MeCab version supports the requested features and avoid problematic format specifiers. You might need to adjust them, for example, `with MeCab(r'-F%m,%f[0],%h,%f[8]
 -U?,?,?,?') as nm:`

natto.api.MeCabError

This general error indicates that `natto-py` could not properly initialize or communicate with the underlying MeCab library, often because MeCab (and its dictionaries) is not installed, not on the system's PATH, or its character set is not correctly configured.

fix

Install MeCab (v0.996+) and a system dictionary (e.g., IPA, Unidic) on your operating system. If `natto-py` cannot automatically locate it, set the `MECAB_PATH` and `MECAB_CHARSET` environment variables (e.g., `os.environ['MECAB_PATH'] = '/path/to/libmecab.so'` and `os.environ['MECAB_CHARSET'] = 'utf8'`) in your Python code before importing `natto`.

Upgrade

Version history

1.0.1latest on PyPI · released Sep 7, 2022

Audit

Dependencies

MeCab (system-wide)requirednatto-py is an FFI binding to the MeCab library and requires a pre-existing MeCab installation (v0.996 or greater) and a system dictionary (e.g., IPA, Unidic) on the host machine. It does not bundle MeCab itself.

cffirequiredUsed for the Foreign Function Interface to MeCab. Automatically installed as a Python dependency with natto-py.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/buruzaemon/natto-py ↗

packagehttps://pypi.org/project/natto-py/ ↗