unhwp

High-performance Python library for extracting HWP/HWPX Korean word processor documents to Markdown.

Installation

pip install unhwp

Quick Start

import unhwp

# Simple conversion
markdown = unhwp.to_markdown("document.hwp")
print(markdown)

# Extract plain text
text = unhwp.extract_text("document.hwp")

# Full parsing with images
with unhwp.parse("document.hwp") as result:
    print(result.markdown)
    print(f"Sections: {result.section_count}")
    print(f"Paragraphs: {result.paragraph_count}")

    # Save images
    for img in result.images:
        img.save(f"output/{img.name}")

Handling Failures

UnhwpError.kind says why a call failed, so you can react to the reason instead of matching on message text:

from unhwp import ErrorKind, ParseError

try:
    with unhwp.parse(path) as result:
        print(result.markdown)
except ParseError as err:
    if err.kind in (ErrorKind.OLE_CONTAINER, ErrorKind.ZIP_ARCHIVE):
        print("The file is damaged.")
    elif err.kind in (ErrorKind.UNKNOWN_FORMAT, ErrorKind.UNSUPPORTED_FORMAT):
        print("Not a supported HWP/HWPX document.")
    elif err.kind in (ErrorKind.ENCRYPTED, ErrorKind.DISTRIBUTION_RESTRICTED):
        print("The document cannot be opened without authorization.")
    else:
        # Also the right branch for a reason this build has no name for.
        print(f"Extraction failed ({err.kind}): {err}")

The numbers behind ErrorKind are a stable ABI contract: a new reason takes the next free number and existing ones are never renumbered. Always keep a final else — an unrecognised value arrives as a plain int rather than an ErrorKind, so that a newer native library stays usable. kind is ErrorKind.OTHER for failures raised by the wrapper itself, and never ErrorKind.NONE (which means success).

Features

Fast: Native Rust library with zero-copy parsing
Complete: Extracts text, tables, images, and document structure
Clean Output: Optional cleanup pipeline for polished Markdown
Format Support: HWP 5.0, HWPX, and HWP 3.x (legacy)

API Reference

Functions

`to_markdown(path) -> str`

Convert an HWP/HWPX document to Markdown.

markdown = unhwp.to_markdown("document.hwp")

`to_markdown_with_cleanup(path, cleanup_options=None) -> str`

Convert with optional cleanup.

markdown = unhwp.to_markdown_with_cleanup(
    "document.hwp",
    cleanup_options=unhwp.CleanupOptions.aggressive()
)

`extract_text(path) -> str`

Extract plain text content.

text = unhwp.extract_text("document.hwp")

`parse(path, render_options=None) -> ParseResult`

Parse a document with full access to content and images.

with unhwp.parse("document.hwp") as result:
    print(result.markdown)
    print(result.text)
    for img in result.images:
        print(img.name, len(img.data))

`detect_format(path) -> int`

Detect the document format.

fmt = unhwp.detect_format("document.hwp")
if fmt == unhwp.FORMAT_HWP5:
    print("HWP 5.0 format")
elif fmt == unhwp.FORMAT_HWPX:
    print("HWPX format")

Classes

`RenderOptions`

Options for Markdown rendering.

opts = unhwp.RenderOptions(
    include_frontmatter=True,
    image_path_prefix="images/",
    preserve_line_breaks=False,
)

`CleanupOptions`

Options for output cleanup.

# Presets
opts = unhwp.CleanupOptions.minimal()
opts = unhwp.CleanupOptions.default()
opts = unhwp.CleanupOptions.aggressive()
opts = unhwp.CleanupOptions.disabled()

# Custom
opts = unhwp.CleanupOptions(
    enabled=True,
    preset=1,
    detect_mojibake=True,
)

Constants

FORMAT_UNKNOWN - Unknown format
FORMAT_HWP5 - HWP 5.0 binary format
FORMAT_HWPX - HWPX XML format
FORMAT_HWP3 - HWP 3.x legacy format

Platform Support

Windows (x64)
Linux (x64)
macOS (x64, ARM64)

Native library

The package ships the native library for your platform. To load another build of it — one you compiled from the Rust crate, say — set UNHWP_LIB_PATH to that file. A path that names no file is an error: importing raises OSError naming the path, rather than quietly loading the packaged library instead.

License

MIT License - see LICENSE for details.

Metadata

Release files for unhwp 0.16.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for unhwp 0.16.0
File	Size	Uploaded
unhwp-0.16.0.tar.gz	8.4 MB	Oct 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for unhwp 0.16.0
File	Interpreter	ABI	Platform	Reset
unhwp-0.16.0-py3-none-any.whl 8.4 MB Oct 9, 2026	Python 3	none	any	Details

Total release size: 16.8 MB

Release files / unhwp-0.16.0.tar.gz

Download URL	unhwp-0.16.0.tar.gz
Size	8.4 MB
Tags	Source
SHA-256 checksum How to use checksums	`cfe7cc51eaff769196feb445c651566d026610742f62d5cacc51bd177f2bdff3`
BLAKE2b-256 checksum How to use checksums	`fc981a3823d71fa8b70e449d0c3403743182ca625f00935d6767bbe7e1d22757`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / unhwp-0.16.0-py3-none-any.whl

Download URL	unhwp-0.16.0-py3-none-any.whl
Size	8.4 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`88a88aca94c25b779253a5d5ace7e52a9278be2ddda2de892f1aeed8913df6df`
BLAKE2b-256 checksum How to use checksums	`3ecc16ae9d2ef7ab4744cf5141a6f213e9926df5aae84c728449b522777bb0ef`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`