파이썬으로 HWP 텍스트 추출하는 방법: pyhwp 설치·사용법부터 한계와 대안까지

파이썬으로 HWP·HWPX 텍스트 추출을 시도하다 막혀본 경험, 생각보다 흔합니다. pyhwp를 설치했는데 Linux 환경에서 에러가 나거나, 표 데이터가 제대로 추출되지 않거나, 개인 PC에서는 잘 작동하던 코드가 서버에 올리는 순간 멈추는 상황이 생깁니다. pyhwp 정의와 설치·사용법부터 어디서 한계가 오는지, 실무에서 쓸 수 있는 현실적인 대안까지 차근차근 정리해 보겠습니다. 

pyhwp란 무엇인가요? 기본 개념과 설치 방법

pyhwp는 HWP 파일의 바이너리 구조를 해석해 텍스트를 추출하는 파이썬 오픈소스 라이브러리입니다. Python 2.7 기반 pre-release 상태라 Python 3 환경에서는 별도 설정이 필요합니다. 

pyhwp 정의와 핵심 기능

AWS에 따르면 파이썬은 웹 개발·데이터 과학·머신러닝에 널리 사용되는 언어로, 137,000개 이상의 라이브러리를 다양한 애플리케이션에 활용할 수 있습니다.

pyhwp는 이 생태계 안에서 HWP 파일 처리를 담당하는 라이브러리로, HWP 5.0 이상 버전을 지원하며 PyPI를 통해 배포되고 있습니다. 내부적으로는 olefile로 스트림을 열어 zlib 압축을 해제한 뒤 텍스트를 읽는 방식으로 작동합니다. 파일 자체를 직접 파싱하는 구조라 한/글 프로그램 설치 없이도 동작하지만, 텍스트 추출에 특화되어 있어 표 안 셀 구조·이미지·문단 계층은 별도로 지원하지 않습니다. 

pyhwp 설치 방법과 문서 활용법

pyhwp 설치는 pip install –user –pre pyhwp 명령어로 진행합니다.

일반적인 pip install pyhwp가 아닌 –pre 플래그가 필요한데, pyhwp가 정식 릴리스 없이 pre-release 베타 상태로 배포되고 있기 때문입니다. –user 플래그는 관리자 권한 없이 사용자 홈 디렉토리에 설치할 때 사용합니다. 오랫동안 공식 업데이트가 없는 상태라 최신 Python 환경에서는 호환 문제가 생길 수 있습니다.

pip install –user –pre pyhwp # pyhwp

💡 가상환경(virtualenv)에서 실행 중이라면 위 명령어에서 –user 옵션을 빼고 pip install –pre pyhwp로 설치합니다. 가상환경은 이미 격리된 공간에 패키지를 설치하기 때문에 –user 옵션이 오히려 충돌해 “Can not perform a ‘–user’ install” 에러가 발생할 수 있습니다.

Windows에서는 setuptools, Lxml이 별도로 필요하고, Linux에서는 setuptools 기반 빌드 환경과 선택적으로 pycrypto가 필요합니다. Python 2.7은 PEP 373에 따라 2020년 1월 1일자로 공식 지원이 종료된 버전 기반이라 Python 3 환경에서 호환 문제가 발생할 수 있습니다.

설치 이후 공식 문서(pythonhosted.org/pyhwp)에서 지원 범위와 기본 사용 방식을 확인할 수 있습니다.

파이썬으로 HWP·HWPX 텍스트 추출하는 방법

파이썬으로 HWP 텍스트를 추출할 땐 pyhwp의 hwp5txt 커맨드라인 도구를 쓸 수 있습니다. 그런데 HWPX는 상황이 다릅니다. HWPX 파일 자체를 직접 파싱하는 pyhwp급의 가벼운 오픈소스 도구는 마땅치 않고, 흔히 대안으로 언급되는 pyhwpx는 파일을 직접 읽는 파서가 아니라 전혀 다른 방식으로 작동합니다. 

pyhwp 기본 사용법: HWP 파일 읽고 텍스트 추출하기 

pyhwp로 텍스트를 추출하는 가장 간단한 방법은 hwp5txt 커맨드라인 도구를 사용하는 방식입니다.

hwp5txt sample.hwp > sample.txt

파일 경로를 지정하면 텍스트로 변환해 출력하며, Python 스크립트 안에서 subprocess로 호출해 자동화 파이프라인에 연결할 수도 있습니다. 단순 텍스트는 잘 추출되지만, 표 안 텍스트는 셀 구조 없이 평면으로 출력됩니다. 공문서처럼 표가 많은 문서일수록 이 한계가 두드러지게 나타납니다.

💡 HWP·HWPX 파일 내부가 어떤 구조로 이루어져 있는지 더 깊이 이해하고 싶다면, 한컴 개발팀이 직접 정리한 기술 블로그를 참고하기 바랍니다.

📚 한컴테크, 한/글 문서 파일 형식: Python을 통한 HWP 포맷 파싱하기 (1)

파이썬 HWPX 텍스트 추출: pyhwpx는 왜 파서가 아닌가요? 

HWP는 바이너리, HWPX는 XML 기반 포맷이라 이론적으로는 구조를 직접 읽어내는 파서를 만들기에 유리한 조건입니다. 하지만 이름 때문에 종종 HWPX 전용 파서로 오해받는 pyhwpx는 실제로는 그런 라이브러리가 아닙니다.

pyhwpx는 파일을 직접 열어 해석하는 게 아니라, PC에 설치된 한/글 프로그램을 pywin32(COM)로 실행시켜 그 프로그램이 문서를 열고 텍스트·표 데이터를 내보내도록 제어하는 자동화 라이브러리입니다. 그래서 한/글 프로그램이 설치된 Windows 환경이 반드시 있어야 하고, 파일만 있으면 동작하는 pyhwp와는 애초에 작동 원리가 다릅니다. 이런 방식이다 보니 RAG처럼 서버에서 대량 문서를 무인 처리해야 하는 작업에는 두 라이브러리 모두 한계가 분명합니다.

파이썬으로 HWP·HWPX 텍스트 추출이 막힐 때, 원인은 무엇인가요?

대부분 pyhwp의 Python 버전·Linux 빌드 호환 문제, 또는 pyhwpx가 파서가 아니라 한/글 프로그램을 원격 조종하는 자동화 도구라 Windows·한/글 설치가 필수라는 점, 여기에 표·이미지 구조화 미지원까지 겹치는 경우가 많습니다. 

Python 버전, Linux 환경에서 pyhwp가 실패하는 이유

pyhwp는 공식적으로 Python 2.7, 3.5~3.8을 지원합니다. 다만 마지막 릴리스가 2020년(0.1b15)이라 이후 나온 Python 3.9 이상 환경에서는 공식 지원 범위 밖이라 호환 문제가 발생할 수 있습니다.

Linux 서버에서는 setuptools 기반 빌드 환경이 필요하고, 최신 Python 버전(3.9 이상)에서는 실행 시 에러가 발생하는 경우가 많습니다. 오류 원인을 하나씩 해결하려 하기보다 도구 선택 자체를 재검토하는 편이 효율적일 수 있습니다. pyhwp는 공식 SDK 기반이 아닌 오픈소스 프로젝트로, 최신 포맷 대응과 구조 정보 처리 측면에서 한계가 있을 수 있습니다. 

pyhwp로 표, 이미지 데이터를 추출할 수 없는 이유

pyhwp는 텍스트 레코드 중심으로 파싱하기 때문에, 표 안의 셀 구조나 이미지 맥락 정보를 추출하지 못합니다.

HWP 포맷에서 표 데이터는 텍스트와 별도의 확장 컨트롤 레코드 구조로 저장되어 있습니다. pyhwp는 이 레코드를 별도로 처리하는 로직을 갖추고 있지 않아 셀 단위 구조를 추출하지 못합니다. 한컴 개발팀이 HWP 포맷 구조를 직접 분석한 내용에서도 이 구조를 확인할 수 있습니다. 

PubTables-1M 연구에 따르면 표는 병합 셀, 다단 헤더 같은 복잡도로 인해 TSR(Table Structure Recognition, 표 구조 인식) 기술 없이는 정확한 추출이 어렵습니다. 결국 TSR 기능이 적용된 도구가 필요합니다.

코드와 함께 정리한 기술 블로그에서 확인할 수 있습니다.

📚 한컴테크, 한/글 문서 파일 형식: Python을 통한 HWP 포맷 파싱하기 (2)

파이썬 HWP·HWPX 라이브러리 종류와 선택 기준

파이썬 HWP·HWPX 라이브러리는 로컬 자동화 방식(pyhwp·pyhwpx), 직접 구현 방식(olefile), 클라우드 API 방식, 온프레미스 솔루션으로 나뉘며 목적과 환경에 따라 적합한 도구가 달라집니다.

한눈에 살펴보는 파이썬 HWP·HWPX 라이브러리 비교

파이썬으로 HWP·HWPX를 처리하는 방법은 크게 네 가지로 나뉩니다. pyhwp는 파일을 직접 파싱하는 반면 pyhwpx는 한/글 프로그램을 자동화하는 도구라 작동 전제 자체가 다르고, 표 구조화·서버 배포·폐쇄망 대응이 필요하다면 선택지가 완전히 달라집니다. 

구분	작동 방식	한/글 설치	텍스트 추출	표 구조화	계층 구조	폐쇄망	대량 배치	비용
pyhwp	파일 직접 파싱	불필요	가능	미지원	미지원	가능	어려움	무료
pyhwpx	한/글 프로그램 자동화(COM)	필요	가능	제한적(GUI 의존)	미지원	가능	어려움	무료
olefile 직접 파싱	직접 파싱(구현 필요)	불필요	직접 구현	직접 구현	직접 구현	가능	직접 설계	무료
클라우드 API	외부 서버 처리	무관	가능	가능	일부	불가	가능	유료
한컴 데이터 로더	원본 직접 파싱	무관	가능	가능	가능	가능	가능	별도 문의

목적과 환경에 따른 HWP·HWPX 라이브러리 선택 기준

단순 텍스트 추출이나 문서 편집이 목적이라면 pyhwp·pyhwpx로 충분합니다. 표 구조화, Linux 서버 배포, 대량 처리, 폐쇄망 환경 중 하나라도 해당된다면 파싱 솔루션 검토가 필요합니다.

✅ Windows 환경에서 소량 처리·단순 텍스트 추출 → pyhwp / pyhwpx

✅ Linux 서버 배포 필요 → 온프레미스 솔루션 또는 클라우드 API 검토

✅ 표·이미지 구조화 필요 → TSR 지원 솔루션 필요

✅ 폐쇄망·공공·금융 환경 → 온프레미스 필수

위 항목 2개 이상 해당 → 파싱 솔루션 검토를 추천합니다.

💡 RAG 파이프라인의 문서 전처리 단계에서 표와 계층 구조까지 함께 추출해야 한다면, 한컴 데이터 로더 데모로 실제 구현을 먼저 확인하기 바랍니다.

👉  한컴 데이터 로더 데모 사용하러 가기

파이썬 HWP·HWPX 자동화, 라이브러리 방식의 한계와 현실적인 대안

단일 파일 수준에서는 라이브러리 방식으로 충분하지만, 서버 배포·대량 처리·폐쇄망 운영까지 요구된다면 라이브러리 방식의 실무 한계가 드러납니다.

대규모, 배치 처리에서 라이브러리 방식의 한계

개인 PC에서 잘 작동하던 pyhwp 코드가 서버에 올라가면 실행 환경 차이 때문에 제대로 작동하지 않거나, 처리할 파일 수가 수백 건으로 늘어나면 속도가 느려지고 오류가 잦아지는 상황이 자주 발생합니다.

pyhwp는 유지보수가 활발하지 않아 HWP·HWPX 포맷 버전 업데이트에 대응하기 어렵고, 대량 배치 처리를 위한 병렬화·큐 관리 같은 운영 기능도 직접 구현해야 합니다. 

pyhwpx 역시 한/글 프로그램을 하나씩 실행해 제어하는 방식이라 대량 파일을 병렬로 처리하기엔 구조적으로 무리가 있습니다.이 운영 부담을 이미 내재화해 해결한 도구가 한컴 데이터 로더입니다.

서버, 폐쇄망 환경에서 현실적인 HWP·HWPX 파싱 대안은?

클라우드 API 방식은 문서를 외부 서버로 전송해야 해서 공공·금융·법무 폐쇄망 환경에서는 사용할 수 없습니다. 이 경우 Docker REST API 기반 온프레미스 파싱 솔루션이 현실적인 대안입니다.

Python의 requests 라이브러리로 API를 호출하면 기존 파이썬 파이프라인에 그대로 연결할 수 있고, 외부 네트워크 없이 내부망에서 완전히 작동하며 CPU 자원만으로도 실행할 수 있습니다.

한컴 데이터 로더는 HWP·HWPX·PDF·OOXML을 구조화 데이터로 전환하는 문서 파싱 솔루션입니다. DLA(Document Layout Analysis, 문서 구조 분석)·OCR(Optical Character Recognition, 광학 문자 인식)·TSR을 통합 파이프라인으로 내재화해 RAG 파이프라인 구축 시 문서 전처리 단계의 부담을 줄여줍니다.

※ 이미지 캡셔닝(Image Captioning) 기능은 현재 PoC 단계로, 상용 출시 일정은 추후 안내될 예정입니다.

파이썬으로 HWP·HWPX 텍스트 추출 시 자주 묻는 질문

파이썬 HWP·HWPX 텍스트 추출, 다음 단계까지 고려하셨나요?

지금까지 살펴본 것처럼 pyhwp, pyhwpx는 단일 파일 텍스트 추출엔 충분합니다. 하지만 표 구조나 문단 계층 구조 보존, Linux 서버 배포, 대량 처리, 폐쇄망 환경까지 요구되면 한계가 드러납니다. RAG 파이프라인에 그대로 흘려보내면 평면 텍스트로는 검색 정확도를 끌어올리기 어렵습니다.

문제는 HWP·HWPX가 한국 공공, 금융, 법무 문서의 표준인데도 원본 파일을 직접 파싱하는 도구가 없어 PDF로 변환해 우회 처리하는 과정에서 표 구조와 문서 계층 정보가 사라진다는 점입니다. 클라우드 API는 폐쇄망에서 외부 전송이 불가능합니다. 국내 문서 환경에는 처음부터 이 조건을 전제로 설계된 솔루션이 필요합니다.

🖥️한컴 데이터 로더

한컴 데이터 로더는 HWP·HWPX·PDF·OOXML을 구조화 데이터로 전환하는 문서 파싱 솔루션입니다. RAG 파이프라인 구축 시 문서 전처리 단계에서 발생하는 정보 누락 문제를 줄일 수 있습니다.

✅ HWP SDK 원천 기술 기반 HWP·HWPX 원본 직접 파싱으로 PDF 변환 손실 최소화 

✅ DLA, TSR, OCR을 외부 의존 없이 단일 파이프라인으로 처리

✅ Level 추론 엔진으로 한국어 공문서, 법령 위계 구조까지 자동 태깅해 청킹 품질 확보

✅ Docker REST API 온프레미스 완전 내재화로 폐쇄망 환경에서도 외부 전송 없이 운용

✅ GS 인증 보유로 공공, 금융, 법무 기관 납품 레퍼런스 확보

pyhwp로 막혔다면, 텍스트와 함께 표와 계층까지 추출하는 환경부터 점검하기 바랍니다.

👉 한컴 데이터 로더 둘러보기

👉 한컴 데이터 로더 도입 문의하기

---

참고자료

1. AWS, 「Python이란 무엇인가요?」
2. Python Software Foundation, 「PEP 373 – Python 2.7 Release Schedule」
3. pyhwp 공식 문서
4. pyhwp 변환기 문서
5. pyhwp PyPI 페이지
6. 한컴테크, 「한/글 문서 파일 형식: Python을 통한 HWP 포맷 파싱하기 (1)」
7. 한컴테크, 「한/글 문서 파일 형식: Python을 통한 HWP 포맷 파싱하기 (2)」
8. 한컴, 「한/글 문서 파일 형식 5.0 revision 1.3」
9. Smock et al., 「PubTables-1M: Towards Comprehensive Table Extraction from Unstructured Documents」
10. Lewis et al., 「Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks」
11. Liu et al., 「Lost in the Middle: How Language Models Use Long Contexts」