kiwipiepy

library0.23.2pypypi✓ verified 85d ago

Kiwipiepy is a fast and accurate Korean morphological analyzer (tokenizer) for Python, wrapping the high-performance C++ library Kiwi. It supports various features like part-of-speech tagging, named entity recognition, dialect analysis, and typo correction. The library is actively maintained with frequent updates, often aligning with the core Kiwi library's releases.

ai-ml data

pip install kiwipiepy

github ↗package ↗

INSTALL

IMPORT

SIG · KIWIPIEPY

kiwipiepy

ai-mlpythonv0.23.2

Install

11.8s avg

Import

172ms

Disk

233MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.23.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

py 3.10–3.910 runs

build_error

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 11.8s · import 0.172s · 232MB

233MB installed

● package 233MB

Code

Verified usage

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

Kiwi

✓ from kiwipiepy import Kiwi

This quickstart demonstrates how to initialize the `Kiwi` tokenizer and perform basic morphological analysis on a Korean sentence. It also includes an example of using the `split_complex` option for more granular analysis.

from kiwipiepy import Kiwi # Initialize the Kiwi tokenizer kiwi = Kiwi() # Analyze a Korean sentence text = "안녕하세요 한국어 형태소 분석기 키위입니다." result = kiwi.tokenize(text) # Print the analysis result for token in result: print(f"Token: {token.form}, Tag: {token.tag}, Start: {token.start}, Len: {token.len}") # Example with additional options (e.g., split complex words) text_complex = "그녀는책을읽었다" result_complex = kiwi.tokenize(text_complex, split_complex=True) print("\nComplex word analysis:") for token in result_complex: print(f"Token: {token.form}, Tag: {token.tag}")

kiwi --version

Debug

Known issues

breakingThe `oov_handling` parameter has moved from the `Kiwi` constructor to the `tokenize()` method and now supports new strategies. Old code passing `oov_handling` to `Kiwi()` will break.

fix

Move `oov_handling` from `Kiwi(oov_handling=...)` to `kiwi.tokenize(text, oov_handling=...)`. Check documentation for new valid `oov_handling` string values.

affects: 0.23.0+

breakingTypo correction options like `typos`, `match_typo_with_stem` have moved from the `Kiwi` constructor to the `tokenize()` method. Passing them during initialization will result in a `TypeError`.

fix

Pass typo correction options to `kiwi.tokenize(text, typos=True, match_typo_with_stem=True, ...)` instead of `Kiwi(typos=True, ...)`.

affects: 0.23.0+

deprecatedThe `knlm` and `sbg` (older, smaller) model types are no longer the default options. Specifying `model_type='knlm'` or `model_type='sbg'` (older) might lead to warnings or unexpected behavior.

fix

Use the default `model_type` or explicitly specify `model_type='sbg'` (the current default and recommended general-purpose model) or `model_type='ngram'`.

affects: 0.22.1+

gotchaWhile v0.22.0 improved multithread safety for `Kiwi` objects, concurrent modifications to user dictionaries or other internal states shared across threads using a single `Kiwi` instance can still lead to unexpected behavior or race conditions. Creating a `Kiwi` instance per thread is generally safer for heavy concurrent use cases.

fix

For critical multithreaded applications, create a separate `Kiwi` instance for each thread or ensure any dictionary modifications are synchronized.

affects: All versions, especially pre-0.22.0

gotchaIn earlier versions, operations like `Kiwi.join()` could potentially fail or lead to incorrect results if the `Kiwi` instance or its associated `MorphemeSet` was modified or deleted after tokenization, due to lingering references.

fix

Ensure the `Kiwi` instance remains stable and in scope when performing subsequent operations like `join()` on results obtained from it. Upgrade to the latest version to benefit from fixes in v0.22.0.

affects: 0.20.0 - 0.21.x

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'kiwipiepy'

The kiwipiepy library is not installed in the current Python environment.

fix

Run `pip install kiwipiepy` to install the library.

TypeError: Kiwi.__init__() got an unexpected keyword argument 'oov_handling'

Attempting to pass `oov_handling` as an argument to the `Kiwi` constructor in versions 0.23.0 or later.

fix

Move the `oov_handling` argument to the `kiwi.tokenize()` method: `kiwi.tokenize(text, oov_handling='new_strategy')`.

TypeError: Kiwi.__init__() got an unexpected keyword argument 'typos'

Attempting to pass typo correction options (`typos`, `match_typo_with_stem`, etc.) to the `Kiwi` constructor in versions 0.23.0 or later.

fix

Move typo correction options to the `kiwi.tokenize()` method: `kiwi.tokenize(text, typos=True, match_typo_with_stem=True)`.

ValueError: invalid model_type 'knlm'

Using an outdated or unrecognized `model_type` when initializing `Kiwi`.

fix

Remove the `model_type` argument to use the default, or use a currently supported model type like `model_type='sbg'` or `model_type='ngram'`.

segmentation fault (core dumped)

While many segfaults were fixed in later versions (e.g., v0.20.1, v0.20.4, v0.22.0) related to specific inputs, pretokenized spans, or typo correction, some specific edge cases might still trigger them, often involving complex inputs or concurrent dictionary modifications.

fix

Ensure you are on the latest `kiwipiepy` version. If the issue persists, simplify the input, avoid concurrent dictionary modifications, or report the specific input that causes the crash to the library maintainers.

Upgrade

Version history

0.23.2latest on PyPI · released Jun 11, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

49 hits · last 30 days

node

Resources

githubhttps://github.com/bab2min/kiwipiepy ↗

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