konlpy

library0.6.0pypypi✓ verified 85d ago

KoNLPy (Korean Natural Language Processing in Python) is a Python package designed for Korean text analysis. It provides a consistent API for various popular Korean NLP tools written primarily in Java, including Hannanum, Kkma, Komoran, Mecab (unsupported on Windows), and Okt (Open Korean Text). The current version is 0.6.0, and while its release cadence is irregular, the library is actively maintained to integrate new upstream NLP tools.

ai-ml llm-agents

pip install konlpy

package ↗homepage ↗

INSTALL

IMPORT

SIG · KONLPY

konlpy

ai-mlpythonv0.6.0

Install

4.7s avg

Import

440ms

Disk

122MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

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

✓ 5.05s

py 3.11

✕ build_error

✓ 4.65s

py 3.12

✕ build_error

✓ 4.4s

py 3.13

✕ build_error

✓ 4.55s

py 3.9

✕ build_error

1/2 runs

122MB installed

● package 122MB

Code

Verified usage

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

Okt

✓ from konlpy.tag import Okt

Kkma

✓ from konlpy.tag import Kkma

Komoran

✓ from konlpy.tag import Komoran

Mecab

✓ from konlpy.tag import Mecab

Mecab is not officially supported on Windows and requires additional system-level installation (e.g., `python-mecab-ko` and `mecab-ko-dic`) on other OSes.

Hannanum

✓ from konlpy.tag import Hannanum

This quickstart demonstrates basic Korean text processing using the `Okt` (Open Korean Text) tagger, including morphological analysis, part-of-speech tagging, and noun extraction. Ensure a JDK is installed and configured for this to run.

from konlpy.tag import Okt okt = Okt() text = "아버지가 방에 들어가신다." print(f"Original text: {text}") print(f"Tokenization: {okt.morphs(text)}") print(f"Part-of-speech tagging: {okt.pos(text)}") print(f"Nouns: {okt.nouns(text)}")

Debug

Known issues

breakingKoNLPy relies on Java-based NLP tools and therefore requires a Java Development Kit (JDK) 8 or higher to be installed and properly configured in your system's PATH. Without a correctly configured JVM, most taggers will fail to initialize or run, often with `OSError: 'JVM' is not running.`

fix

Install a JDK 8+ (e.g., OpenJDK). Set the `JAVA_HOME` environment variable to your JDK installation directory and add `%JAVA_HOME%\bin` (Windows) or `$JAVA_HOME/bin` (Linux/macOS) to your system's PATH. Restart your terminal/IDE after configuration.

affects: All versions

gotchaThe Mecab tagger (`konlpy.tag.Mecab`) is not officially supported on Windows due to its reliance on a C++ library and specific dictionary setup. Installation on non-Linux/macOS systems can be very challenging and prone to errors.

fix

On Windows, avoid using `Mecab` and opt for alternative taggers like `Okt`, `Komoran`, `Kkma`, or `Hannanum`. On Linux/macOS, follow the specific system-level installation instructions (e.g., `pip install python-mecab-ko` and `mecab-ko-dic`) provided on the KoNLPy GitHub repository.

affects: All versions

gotchaProcessing very large texts or numerous documents concurrently can lead to `java.lang.OutOfMemoryError: Java heap space` errors. This is due to the underlying JVM's default memory limits.

fix

Increase the JVM's maximum heap space by setting the `_JAVA_OPTIONS` environment variable before running your Python script. For example, `export _JAVA_OPTIONS="-Xmx4g"` (Linux/macOS) or `set _JAVA_OPTIONS="-Xmx4g"` (Windows) will allocate 4GB. Adjust the `Xmx` value as needed.

affects: All versions

Errors

Common errors & fixes

OSError: 'JVM' is not running.

The Java Development Kit (JDK) is either not installed, not found in the system's PATH, or the `JAVA_HOME` environment variable is not correctly set. The underlying JPype library cannot locate an available Java Virtual Machine.

fix

Install JDK 8 or higher (e.g., OpenJDK). Set the `JAVA_HOME` environment variable to the root directory of your JDK installation (e.g., `C:\Program Files\Java\jdk-11` or `/usr/lib/jvm/java-11-openjdk`). Add the `bin` subdirectory of your JDK (`%JAVA_HOME%\bin` or `$JAVA_HOME/bin`) to your system's PATH environment variable. Restart your terminal/IDE.

FileNotFoundError: 'mecab-ko-dic' not found.

The Mecab dictionary required by the `Mecab` tagger is missing or incorrectly configured. This often happens on systems where Mecab is not fully supported (like Windows) or if its complex dependencies weren't met during installation.

fix

If on Windows, consider using `Okt`, `Komoran`, `Kkma`, or `Hannanum` instead of `Mecab`. On Linux/macOS, ensure Mecab and its dictionary (`mecab-ko-dic`) are correctly installed by following specific instructions for your OS, which typically involves installing `python-mecab-ko`.

java.lang.OutOfMemoryError: Java heap space

The Java Virtual Machine (JVM) that KoNLPy uses has exhausted its allocated memory. This usually occurs when processing extremely long texts or a large volume of data.

fix

Increase the JVM's maximum heap size. You can do this by setting the `_JAVA_OPTIONS` environment variable before running your Python script. For example, to allocate 4GB of memory, use `export _JAVA_OPTIONS="-Xmx4g"` on Linux/macOS or `set _JAVA_OPTIONS="-Xmx4g"` on Windows.

AttributeError: module 'konlpy' has no attribute 'tag'

This error occurs when attempting to call a tagger directly from the top-level `konlpy` module (e.g., `konlpy.tag.Okt()`) without correctly importing the `tag` submodule or the specific tagger class.

fix

Ensure you import the tagger class correctly. The standard way is `from konlpy.tag import Okt` and then `okt = Okt()`. Alternatively, you can import the submodule as `from konlpy import tag` and then use `tagger = tag.Okt()`.

Upgrade

Version history

0.6.0latest on PyPI · released Jan 2, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

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

homepagehttp://konlpy.org ↗