How I Converted 1,659 Hangul Files into Markdown Files
(Just ask Claude Cowork to do it)

HWP/HWPX → Markdown Local Batch Conversion Guide

Without external services, on my own computer, with a few terminal commands

There were 1,659 Hangul files on the computer. HWP 563 files, HWPX 1,096 files. Manuscripts, legal documents, lecture materials, travelogues, and policy reports accumulated over years were all trapped in the Hangul format. To have AI read them, I needed to extract the text, but opening the Hangul program one by one and copying and pasting 1,659 times was out of the question.

With one Python open-source library, it was done in 6 minutes. Success rate 99.3%.

HWP and HWPX, What Is the Difference?

HWPX is actually a ZIP file. If you change the extension to .zip and unzip it, XML files come out. The body text is in Contents/section0.xml, and the XML structure is neatly organized as p (paragraph) > run (formatting) > t (text). Because Hancom created the format as an open standard called OWPML (KS X 6101), it is easy to parse.

HWP is an old-style binary file. It uses the same OLE2 container structure as Microsoft Word's .doc files. The internal data is compressed with zlib and the record structure is complex. Still, Hancom has disclosed the binary specification, so open-source parsers exist.

Both can be converted. The tool is called pyhwp2md.

Core Tool: pyhwp2md

After investigating several open-source projects, I found a Python library called pyhwp2md. MIT license. It converts both HWP (binary) and HWPX (XML) to Markdown. Internally, it combines pyhwp, a binary parser, and python-hwpx, an XML parser. Paragraphs, headings, and even tables are converted.

Step 1. Install Python 3.10 or Later

pyhwp2md requires Python 3.10 or later. The default Python on macOS is 3.9.6, so it will not work. Install it with Homebrew.

Terminal command:

# Check the current Python version

python3 --version



# If it is below 3.10, install it with Homebrew

/opt/homebrew/bin/brew install python@3.12



# Confirm the installation

/opt/homebrew/opt/python@3.12/bin/python3.12 --version

Windows users can download the 3.12 installer from python.org.

Step 2. Create a Virtual Environment

Create an independent environment without touching the system Python. Just create a venv folder at the path you want.

Terminal command:

# Create a virtual environment, choose any path you like

/opt/homebrew/opt/python@3.12/bin/python3.12 -m venv ~/hwp_convert_venv



# Activate the virtual environment

source ~/hwp_convert_venv/bin/activate



# Confirm activation, it worked if Python 3.12.x appears

python --version

On Windows, the activation command is different:

hwp_convert_venv\Scripts\activate

Step 3. Install pyhwp2md

One line of pip is enough. Dependency libraries such as pyhwp, python-hwpx, lxml, and olefile are automatically installed together.

Terminal command:

pip install --upgrade pip

pip install pyhwp2md

After installation, a CLI command called pyhwp2md is created. At the same time, you can also import it inside Python code with from pyhwp2md import convert.

Step 4. Test with One File

Before batch conversion, check with one file first.

Terminal command:

# Print Markdown to the screen without saving

pyhwp2md "my-document.hwpx"



# Save as an .md file in the same folder, using the -s option

pyhwp2md "my-document.hwpx" -s



# Save to the path you choose

pyhwp2md "my-document.hwp" -o "results/my-document.md"

When I tested with an HWPX file, the body text came out cleanly as Markdown. The same was true for HWP binary files. Tables were also converted into Markdown table syntax.

Step 5. Create a Batch Conversion Script

If there are only dozens of files, you can run them one by one with the -s option. But if there are hundreds or thousands, you need a Python script.

Save the script below as hwp_convert.py. The key is one TARGET_DIR variable. Put your folder path there, and it will find all HWP/HWPX files under that folder and create .md files with the same names in the same locations.

hwp_convert.py:

#!/usr/bin/env python3

"""Batch conversion from HWP/HWPX to Markdown"""



import time

from pathlib import Path

from pyhwp2md import convert



##############################################

# Change this to your own folder path

##############################################

TARGET_DIR = Path.home() / "Documents"



files = []

for ext in ("*.hwp", "*.hwpx"):

    files.extend(TARGET_DIR.rglob(ext))

files = sorted(files)



print(f"Found: {len(files)} files")



ok = fail = skip = 0

failures = []

start = time.time()



for i, f in enumerate(files, 1):

    md = f.with_suffix(".md")

    if md.exists():

        skip += 1

        continue

    try:

        content = convert(str(f))

        if not content or not content.strip():

            fail += 1

            failures.append((f, "empty output"))

            continue

        md.write_text(content, encoding="utf-8")

        ok += 1

    except Exception as e:

        fail += 1

        failures.append((f, str(e)[:100]))

    if i % 50 == 0:

        print(f"[{i}/{len(files)}] success:{ok} failed:{fail}")



elapsed = time.time() - start

print(f"\nDone. Took {elapsed:.0f} seconds")

print(f"Success: {ok} | skipped: {skip} | failed: {fail}")



if failures:

    print("\nFailure list:")

    for path, msg in failures:

        print(f"  {path.name}: {msg}")

Step 6. Run It

Terminal command:

# Activate the virtual environment

source ~/hwp_convert_venv/bin/activate



# Run the script

python hwp_convert.py

That is all. Progress is printed every 50 files. When it finishes, it shows the number of successes and failures and the list of failed files.

Real-World Result

I ran it across the entire iCloud Drive.

Target files: 1,659 (HWP 563 + HWPX 1,096)

Success: 1,639

Skipped: 9, because .md files already existed

Failed: 11 (0.7%)

Time: 356 seconds, about 6 minutes

Success rate: 99.3%

The 11 failures were files whose originals had no text, consisting only of tables or images, or damaged HWP files. Every file with text was successfully converted.

Collection of TARGET_DIR Path Examples

By changing only TARGET_DIR in the script, you can target any folder.

# Korean files on the desktop only

TARGET_DIR = Path.home() / "Desktop"



# The entire Documents folder

TARGET_DIR = Path.home() / "Documents"



# iCloud Drive

TARGET_DIR = Path.home() / "Library/Mobile Documents/com~apple~CloudDocs"



# External drive or USB

TARGET_DIR = Path("/Volumes/MyDrive/KoreanFiles")



# One specific project folder

TARGET_DIR = Path.home() / "Documents/2024Project/Reports"



# Windows user

TARGET_DIR = Path("C:/Users/YourName/Documents")



# Windows OneDrive

TARGET_DIR = Path("C:/Users/YourName/OneDrive/Documents")

How to Do It with One Terminal Line Without a Script

If the number of files is small, you can do it without a script.

# Convert every hwpx file in the current folder at once

for f in *.hwpx; do pyhwp2md "$f" -s; done



# Include hwp files too

for f in *.hwp *.hwpx; do pyhwp2md "$f" -s; done



# Include all subfolders

find ~/Documents -name "*.hwp" -o -name "*.hwpx" | \

  while read f; do pyhwp2md "$f" -s; done

What Can You Do After Conversion?

Markdown files are text files. AI can read them directly. You can put them into Claude, ChatGPT, NotebookLM, anywhere. They can also be searched in note apps like Obsidian. With one line of grep, you can find keywords across thousands of documents. You no longer need to open the Hangul program.

The original HWP/HWPX files remain as they are, so when you need formatting, you can open the originals. Markdown is a copy with the text extracted.

When new Hangul files are added later, run the same script again. Files that already have .md versions are automatically skipped. Only new files are converted.

No matter how many Hangul files you have, there is no need to be intimidated. One line, pip install pyhwp2md, is the start, and a 30-line Python script is the end.

Related Open-Source Projects

• pyhwp2md - Converts HWP/HWPX to Markdown, the tool used in this article
https://github.com/pitzcarraldo/pyhwp2md

• python-hwpx - Library for reading/writing/creating HWPX
https://github.com/airmang/python-hwpx

• pyhwp - HWP binary parser
https://github.com/mete0r/pyhwp

• hwp.js - JavaScript HWP parser/viewer
https://github.com/hahnlee/hwp.js

• H2Orestart - LibreOffice HWP/HWPX extension
https://github.com/ebandal/H2Orestart

• hwpx-contents-extract - Hancom official HWPX extraction example (Java)
https://github.com/hancom-io/hwpx-contents-extract