python-hwpx

한컴오피스 없이 한/글 문서(HWPX·HWP)를 읽고 고치고 만드는 파이썬 라이브러리

한국어 | English

HWPX는 ZIP 안에 XML(OWPML)을 담은 형식이라, 한컴오피스가 없어도 파이썬만으로 다룰 수 있습니다. python-hwpx는 Windows·macOS·Linux·CI 어디서나 돌고 의존성은 lxml 하나입니다. HWP 5.0(.hwp)도 같은 API로 열고 저장합니다.

만든 문서는 한컴오피스 2024에서 직접 열어 보고 그 결과를 날짜와 함께 아래에 적어 둡니다.

시작하기

pip install python-hwpx      # Python 3.10+

from hwpx import HwpxDocument

doc = HwpxDocument.new()
doc.add_heading("2026 운영계획", level=1)
doc.add_paragraph("추진 배경", style="개요 2")  # 한/글이 "가." 번호를 붙인다
doc.save_to_path("계획.hwpx")

스타일은 이름으로 고릅니다. 없는 이름을 쓰면 그 줄에서 바로 오류가 납니다. 있는 문서를 고칠 때는 HwpxDocument.open("보고서.hwpx")로 시작합니다. .hwp도 똑같이 열고, save_to_path("보고서.hwp")로 HWP 5.0으로 저장할 수 있습니다.

문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면 python-hwpx-automation을 함께 설치하세요.

예전 설치 명령을 위해 pip install "python-hwpx[visual]"도 계속 됩니다. 다만 이 extra는 비어 있어 렌더·PDF 의존성을 설치하지 않습니다. 그 일은 python-hwpx-automation[oracle]이 맡습니다.

할 수 있는 것

• 읽기·추출: 텍스트·HTML·Markdown으로 내보냅니다. 서식, 표 안의 표, 각주를 살립니다.
• 편집: 문단·표·그림·머리말/꼬리말·메모·각주, 줄 간격·여백·쪽 번호 같은 서식을 고칩니다.
• 양식 채우기: 라벨로 칸을 찾아 값만 넣고 손대지 않은 부분은 바이트 그대로 둡니다. FormFit은 값이 칸에 들어가도록 줄을 바꾸거나 글자를 줄일지 한/글의 글자 폭으로 재서 고릅니다.
• 표 구조 편집: 행·열 넣기와 지우기, 칸 나누기와 합치기. doc.tables[0]처럼 번호로 표를 꺼냅니다.
• 만들기·일괄 처리: 새 문서, 목차·상호 참조, 메일 머지, 문서 비교, 변경 추적.
• HWP 5.0: .hwp를 HWPX로 읽어 같은 API로 고치고 .hwp로 저장합니다. 옮기지 못한 내용은 document.conversion_report에 남습니다.
• 배치 추정(실험): estimate_pages는 한/글 없이 쪽 수와 줄마다의 쪽·세로 위치를 추정합니다. write_line_caches는 한/글이 저장할 때 쓰는 줄 배치 정보를, 한/글과 같은 값을 확실히 아는 문단에만 씁니다. rhwp처럼 이 정보로 그림 자리를 찾는 뷰어에서도 그림이 보이게 됩니다. 기본으로는 쓰지 않습니다.
• 검증·안전: 패키지 구조 검사 CLI, 저장 전 열림 검사, 저장 결과 보고(return_report=True).

자세한 내용: 5분 퀵스타트 · 사용 가이드 · API 레퍼런스 · 예제 · 지원 매트릭스

양식 채우기 예

doc = HwpxDocument.open("신청서.hwpx")
values = {
    "성명 > right": "홍길동",
    "소속 > right": "플랫폼팀",
}
result = doc.tables.fill_by_path(values)
if result["failed_count"] or result["applied_count"] != len(values):
    raise ValueError(result["failed"])
report = doc.save_to_path("신청서-작성완료.hwpx", mode="patch", fallback="error", return_report=True)

라벨이 겹치거나 없으면 실패로 돌려주고 저장하기 전에 멈출 수 있습니다. mode="patch"는 고치지 않은 ZIP 파트를 바이트 그대로 두라는 뜻입니다. 고친 파트 안쪽과 화면 배치는 따로 확인해야 합니다. 저장한 파일을 다시 열어 내용까지 확인하는 방법은 안전한 쓰기 계약에 있습니다.

독립 실행 예제로 표시하지 않은 블록은 여러분이 가진 문서를 입력으로 쓰는 조각입니다. 예제별 Python 블록 판정은 실행 기록에 남겨 둡니다.

한/글과 얼마나 같은가

만든 파일을 실제 한컴오피스로 열어 보고 그대로 적습니다. 숫자마다 잰 날짜와 프로그램 판을 붙입니다.

배치: python-hwpx 6.9 이후 main · 2026-10-25

열림: 한컴오피스 12 (macOS)

• 한컴에서 열림 120/120, 렌더 검증 120/120: 기준 문서와 저작 기능 6종(각주·누름틀·수식·차트·체크박스·편집 계획)을 줄여서 잰 것 (5.7.0 · 2026-08-03)
• 한컴에서 열림 476/476: 동결한 코퍼스 전체(N=497) (3.4.1 · 2026-07-19)
• 고치지 않은 영역의 바이트 보존 497/497, 개인정보 유출 0
• 렌더 검증 416/476: 한컴이 PDF 내보내기를 거부한 43건도 빼지 않고 셌습니다.

_{ChatGPT 실행 환경에서 만든 문서를 실제 한컴오피스로 연 모습.}

전체 숫자와 주의할 점은 실측 코퍼스 메트릭에, 기능별 등급은 지원 매트릭스에 있습니다. 이 숫자들은 "만든 파일을 한/글이 어떻게 받는가"를 잰 것이고 파서가 문서를 얼마나 잘 읽는지와는 다른 지표입니다.

개발 단계는 Beta입니다. 하위 호환을 지키는 범위는 안정 API 표면에 적혀 있고, hwpx.experimental과 위에서 "실험"이라고 적은 기능은 바뀔 수 있습니다.

어디서 쓰나

_{일반 ChatGPT 대화에서 양식 .hwpx를 올리고 부탁하면, 서식은 그대로이고 값만 채운 문서가 돌아옵니다.}

ChatGPT 채팅의 파이썬 환경은 PyPI에 접속하지 못합니다. 그래서 최신 Release의 python_hwpx-*.whl을 문서와 함께 올리고 이렇게 부탁합니다.

첨부한 python_hwpx-*.whl 을 pip 로 설치한 다음(pip install /mnt/data/python_hwpx-*.whl),
이 .hwpx 파일을 python-hwpx 라이브러리로 열어서 작업해줘.
양식과 서식은 그대로 두고, ○○만 바꿔서 새 파일로 돌려줘.

설치부터 결과 파일까지 대화 안에서 끝나므로 내 컴퓨터에 파이썬이 없어도 됩니다. wheel의 의존성은 lxml 하나이고 실행 환경에 없으면 lxml wheel도 함께 올립니다. 에이전트용 지시문은 AI 채팅 환경에서 쓰기에, AI 도구가 API를 정확히 익히도록 만든 llms.txt도 있습니다.

비교

알려진 제약

• add_shape()·add_control()은 저수준 탈출구라, 그대로 저장하면 한/글이 열지 못하는 파일이 됩니다(부를 때 경고만 나옵니다). 도형은 한/글이 요구하는 하위 요소까지 만드는 add_line()·add_rectangle()·add_ellipse()· add_arc()·add_polygon()·add_curve()·add_connector()·add_container()(묶음)를, 컨트롤은 add_column_definition()·add_bookmark()·add_hyperlink()를 쓰세요.
• 그림은 밝기·대비·회색조·흑백·투명도, 실선 테두리, 자르기(crop), 그림자·빛남·부드러운 가장자리·반사 (shadow·glow·soft_edge·reflection)를 add_picture() 인자로 줄 수 있습니다. 뒤집기와 회전은 아직 안 됩니다.
• 쪽 수 추정과 줄 배치 정보 쓰기는 실험 기능입니다. 따르지 못하는 요소가 있으면 추정하지 않고 까닭을 돌려줍니다. 지금은 줄 배치 정보 없이 글자 격자를 쓰는 문단, 그리고 표 칸 안에서 글 사이에 놓이거나 떠 있는 표 가운데 쪽 끝이 어울림·글 뒤·앞 표나 여러 줄짜리 행을 가로지르는 경우가 여기에 듭니다. 그 밖의 칸 안 표는 쪽 끝에서 행 사이로 나뉘는 것까지 한/글처럼 배치합니다. 표를 읽고 고치는 기능은 이와 상관없이 표 안의 표까지 다룹니다.
• 암호를 건 HWPX와 암호·배포용 HWP는 지원하지 않습니다(HWP는 Hwp5Error로 거부합니다).

기여하기

help wanted · 로드맵 · Discussions · CONTRIBUTING

HWPX 내부 구조가 처음이라면 내부 실전 가이드부터 보세요. 실제 한/글 동작으로 확인한 조판 캐시, 목차 필드, OPC 재압축 같은 내용을 정리해 두었습니다. 공개 API의 안정 범위는 안정 API 표면, 계층 사이의 소유권은 제품 경계 문서에 있습니다.

감사의 말

아래 공개 표준과 프로젝트에 빚지고 있습니다.

• OWPML, 개방형 워드프로세서 마크업 언어 (KS X 6101): HWPX의 바탕인 한국 산업 표준
• hancom-io/hwpx-owpml-model: OWPML 요소 구조 참조 모델
• neolord0/hwpxlib: 견본 코퍼스
• edwardkim/rhwp: 멱등성·검증 게이트 설계에서 영감을 받았고 다른 뷰어 호환을 확인할 때 씁니다
• 범정부오피스: 공무 문서 편집 워크플로 아이디어

License · Maintainer

Apache-2.0 (LICENSE · NOTICE) · Kohkyuhyun @airmang · kokyuhyun@hotmail.com