한글 파일 1,659개를 6분 만에 마크다운 파일로 바꾼 방법

작성자

user

작성일

2026-04-09 10:47

조회

2434

한글 파일 1,659개를 마크다운 파일로 바꾼 방법
(클로드 코웍에게 해달라고 시키면된다)

HWP/HWPX → Markdown 로컬 일괄 변환 가이드

외부 서비스 없이, 내 컴퓨터에서, 터미널 명령어 몇 줄로

컴퓨터에 한글 파일이 1,659개 있었다. HWP 563개, HWPX 1,096개. 수년간 쌓인 원고, 법률문서, 강의자료, 여행기, 정책보고서가 전부 한글 포맷에 갇혀 있었다. AI에게 읽히려면 텍스트로 꺼내야 하는데, 한글 프로그램을 하나씩 열어서 복사-붙여넣기를 1,659번 할 수는 없는 노릇이었다.

Python 오픈소스 라이브러리 하나로 6분 만에 끝났다. 성공률 99.3%.

HWP와 HWPX, 뭐가 다른가

HWPX는 사실 ZIP 파일이다. 확장자를 .zip으로 바꿔서 압축을 풀면 XML 파일들이 나온다. Contents/section0.xml에 본문이 들어있고, XML 구조가 p(문단) > run(서식) > t(텍스트)로 깔끔하게 정리되어 있다. 한컴이 OWPML이라는 공개 표준(KS X 6101)으로 만든 포맷이라 파싱이 수월하다.

HWP는 옛날 방식의 바이너리 파일이다. 마이크로소프트 워드의 .doc 파일과 같은 OLE2 컨테이너 구조를 쓴다. 내부 데이터가 zlib으로 압축되어 있고 레코드 구조가 복잡하다. 그래도 한컴이 바이너리 스펙을 공개해놔서 오픈소스 파서들이 존재한다.

둘 다 변환할 수 있다. 도구 이름은 pyhwp2md.

핵심 도구: pyhwp2md

여러 오픈소스를 조사한 끝에 pyhwp2md라는 Python 라이브러리를 찾았다. MIT 라이선스. HWP(바이너리)와 HWPX(XML) 둘 다 마크다운으로 변환한다. 내부적으로 pyhwp(바이너리 파서)와 python-hwpx(XML 파서)를 조합해서 쓴다. 문단, 제목, 표까지 변환된다.

Step 1. Python 3.10 이상 설치하기

pyhwp2md는 Python 3.10 이상을 요구한다. macOS 기본 Python은 3.9.6이라 안 된다. Homebrew로 설치한다.

터미널 명령어:

# 현재 Python 버전 확인

python3 --version



# 3.10 미만이면 Homebrew로 설치

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



# 설치 확인

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

윈도우 사용자는 python.org에서 3.12 설치파일을 받으면 된다.

Step 2. 가상환경 만들기

시스템 Python을 건드리지 않고 독립된 환경을 만든다. 원하는 경로에 venv 폴더를 생성하면 된다.

터미널 명령어:

# 가상환경 생성 (경로는 원하는 곳으로)

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



# 가상환경 활성화

source ~/hwp_convert_venv/bin/activate



# 활성화 확인 (Python 3.12.x 표시되면 성공)

python --version

윈도우에서는 활성화 명령이 다르다:

hwp_convert_venv\Scripts\activate

Step 3. pyhwp2md 설치하기

pip 한 줄이면 끝난다. pyhwp, python-hwpx, lxml, olefile 등 의존 라이브러리가 자동으로 같이 설치된다.

터미널 명령어:

pip install --upgrade pip

pip install pyhwp2md

설치가 끝나면 pyhwp2md라는 CLI 명령어가 생긴다. 동시에 Python 코드 안에서 from pyhwp2md import convert로 불러 쓸 수도 있다.

Step 4. 파일 하나로 테스트하기

일괄 변환 전에 파일 하나로 먼저 확인한다.

터미널 명령어:

# 화면에 마크다운 출력 (저장 안 함)

pyhwp2md "내문서.hwpx"



# 같은 폴더에 .md 파일로 저장 (-s 옵션)

pyhwp2md "내문서.hwpx" -s



# 원하는 경로에 저장

pyhwp2md "내문서.hwp" -o "결과물/내문서.md"

HWPX 파일로 테스트했더니 본문 텍스트가 깔끔하게 마크다운으로 나왔다. HWP 바이너리 파일도 마찬가지였다. 표도 마크다운 테이블 문법으로 변환됐다.

Step 5. 일괄 변환 스크립트 만들기

파일이 수십 개라면 -s 옵션으로 하나씩 돌려도 되지만, 수백에서 수천 개라면 Python 스크립트가 필요하다.

아래 스크립트를 hwp_convert.py라는 이름으로 저장한다. 핵심은 TARGET_DIR 변수 하나. 여기에 자신의 폴더 경로를 넣으면 그 폴더 아래의 모든 HWP/HWPX를 찾아서, 같은 위치에 같은 이름의 .md 파일을 만든다.

hwp_convert.py:

#!/usr/bin/env python3

"""HWP/HWPX → Markdown 일괄 변환"""



import time

from pathlib import Path

from pyhwp2md import convert



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

# 여기를 자신의 폴더 경로로 바꾸세요

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

TARGET_DIR = Path.home() / "Documents"



files = []

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

    files.extend(TARGET_DIR.rglob(ext))

files = sorted(files)



print(f"발견: {len(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, "빈 출력"))

            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)}] 성공:{ok} 실패:{fail}")



elapsed = time.time() - start

print(f"\n완료! {elapsed:.0f}초 소요")

print(f"성공: {ok} | 건너뜀: {skip} | 실패: {fail}")



if failures:

    print("\n실패 목록:")

    for path, msg in failures:

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

Step 6. 실행하기

터미널 명령어:

# 가상환경 활성화

source ~/hwp_convert_venv/bin/activate



# 스크립트 실행

python hwp_convert.py

이게 전부다. 진행 상황이 50개 단위로 출력된다. 끝나면 성공/실패 개수와 실패 파일 목록이 나온다.

실전 결과

iCloud Drive 전체를 대상으로 돌렸다.

대상 파일: 1,659개 (HWP 563 + HWPX 1,096)

성공: 1,639개

건너뜀: 9개 (이미 .md 존재)

실패: 11개 (0.7%)

소요시간: 356초 (약 6분)

성공률: 99.3%

실패한 11개는 원본 자체에 텍스트가 없는 파일(표나 이미지로만 구성)이거나, 손상된 HWP 파일이었다. 텍스트가 있는 파일은 전부 변환에 성공했다.

TARGET_DIR 경로 예시 모음

스크립트의 TARGET_DIR만 바꾸면 어떤 폴더든 대상으로 쓸 수 있다.

# 바탕화면의 한글 파일만

TARGET_DIR = Path.home() / "Desktop"



# 문서 폴더 전체

TARGET_DIR = Path.home() / "Documents"



# iCloud Drive

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



# 외장하드나 USB

TARGET_DIR = Path("/Volumes/MyDrive/한글파일")



# 특정 프로젝트 폴더 하나만

TARGET_DIR = Path.home() / "Documents/2024프로젝트/보고서"



# 윈도우 사용자

TARGET_DIR = Path("C:/Users/사용자이름/Documents")



# 윈도우 원드라이브

TARGET_DIR = Path("C:/Users/사용자이름/OneDrive/문서")

스크립트 없이 터미널 한 줄로 하는 법

파일 수가 적으면 스크립트 없이도 된다.

# 현재 폴더의 모든 hwpx를 한번에 변환

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



# hwp 파일도 포함

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



# 하위 폴더까지 전부 포함

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

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

변환 후 뭘 할 수 있나

마크다운 파일은 텍스트 파일이다. AI가 바로 읽을 수 있다. Claude, ChatGPT, NotebookLM 어디든 넣을 수 있다. Obsidian 같은 노트 앱에서 검색도 된다. grep 한 줄이면 수천 개 문서에서 키워드를 찾을 수 있다. 한글 프로그램을 열 필요가 없어진다.

원본 HWP/HWPX 파일은 그대로 남아있으니 서식이 필요할 때는 원본을 열면 된다. 마크다운은 텍스트를 꺼내 놓은 사본인 셈이다.

나중에 새 한글 파일이 추가되면 같은 스크립트를 다시 돌리면 된다. 이미 .md가 있는 파일은 자동으로 건너뛴다. 새 파일만 변환된다.

한글 파일이 아무리 많아도 겁먹을 필요가 없다. pip install pyhwp2md 한 줄이 시작이고, Python 스크립트 30줄이 끝이다.

인공지능게시판

한글 파일 1,659개를 6분 만에 마크다운 파일로 바꾼 방법

한글 파일 1,659개를 마크다운 파일로 바꾼 방법
(클로드 코웍에게 해달라고 시키면된다)

HWP와 HWPX, 뭐가 다른가

핵심 도구: pyhwp2md

Step 1. Python 3.10 이상 설치하기

Step 2. 가상환경 만들기

Step 3. pyhwp2md 설치하기

Step 4. 파일 하나로 테스트하기

Step 5. 일괄 변환 스크립트 만들기

Step 6. 실행하기

실전 결과

TARGET_DIR 경로 예시 모음

스크립트 없이 터미널 한 줄로 하는 법

변환 후 뭘 할 수 있나

관련 오픈소스 프로젝트

한글 파일 1,659개를 6분 만에 마크다운 파일로 바꾼 방법

한글 파일 1,659개를 마크다운 파일로 바꾼 방법 (클로드 코웍에게 해달라고 시키면된다)

HWP와 HWPX, 뭐가 다른가

핵심 도구: pyhwp2md

Step 1. Python 3.10 이상 설치하기

Step 2. 가상환경 만들기

Step 3. pyhwp2md 설치하기

Step 4. 파일 하나로 테스트하기

Step 5. 일괄 변환 스크립트 만들기

Step 6. 실행하기

실전 결과

TARGET_DIR 경로 예시 모음

스크립트 없이 터미널 한 줄로 하는 법

변환 후 뭘 할 수 있나

관련 오픈소스 프로젝트

한글 파일 1,659개를 마크다운 파일로 바꾼 방법
(클로드 코웍에게 해달라고 시키면된다)