한글(HWP) 파일도 파이썬으로 자동화하기! 텍스트 추출·일괄 변환 (완성 코드 공개)
"관공서에서 받은 공문이 전부 HWP 파일이라 내용을 정리하기 번거롭다", "수십 개의 HWP 견적서를 PDF로 일괄 변환해서 발송해야 한다", "HWP 문서에서 특정 정보만 추출해 엑셀로 정리하고 싶다"…
HWP는 한국에서 관공서와 기업이 여전히 많이 사용하는 문서 형식입니다. 일반적인 파이썬 라이브러리는 HWP를 직접 지원하지 않지만, 한글과컴퓨터에서 제공하는 한글 자동화 API(pyhwpx)를 사용하면 한글 프로그램이 설치된 환경에서 파이썬으로 HWP 파일을 열고, 텍스트를 추출하고, PDF로 변환하는 작업을 자동화할 수 있습니다.
⚠️ 필수 조건: 이 방법은 PC에 한글(HWP) 프로그램이 실제로 설치되어 있어야 동작합니다. 한글 프로그램 없이는 HWP 파일을 직접 처리할 수 없습니다. 한글이 없는 서버 환경이라면 변환 전용 클라우드 서비스를 고려해야 합니다.
1단계: 준비물 설치
PC에 한글(HWP) 프로그램이 설치되어 있어야 합니다. 또한 파이썬이 설치되어 있어야 합니다. 없다면 python.org에서 최신 버전을 받아 설치하세요. 설치 시 반드시 "Add Python to PATH"에 체크해야 합니다.
HWP 자동화 라이브러리를 설치합니다. 터미널(윈도우: CMD 또는 파워셸)을 열고 아래 명령어를 실행하세요:
pip install pyhwpx
pyhwpx는 한글 프로그램의 자동화 API(OLE)를 파이썬에서 쉽게 사용할 수 있도록 감싼 라이브러리입니다. 한글을 백그라운드에서 실행해 파일을 열고, 텍스트를 추출하고, 다른 형식으로 저장하는 기능을 제공합니다.
💡 이 코드로 할 수 있는 것: HWP 파일의 전체 텍스트 추출, 폴더 안의 여러 HWP를 PDF로 일괄 변환, 특정 페이지 또는 구간만 추출, 워드(.docx)로 변환까지 처리합니다.
2단계: 완성 코드 — 텍스트 추출
아래 코드를 그대로 복사해서 메모장에 붙여넣고, hwp_extract.py로 저장하세요. 저장 시 파일 형식은 "모든 파일", 인코딩은 UTF-8로 설정합니다.
from pyhwpx import Hwp
from pathlib import Path
# ① 설정
HWP_PATH = r"C:\Users\내이름\Desktop\공문.hwp" # ← 추출할 HWP 경로
OUTPUT_TXT = r"C:\Users\내이름\Desktop\공문_텍스트.txt" # ← 저장할 텍스트 경로
# ② 한글 프로그램 실행 및 파일 열기
hwp = Hwp(visible=False) # visible=False: 화면에 안 보이게 백그라운드 실행
hwp.open(HWP_PATH)
print(f" ✔ HWP 파일 열기 완료: {Path(HWP_PATH).name}")
# ③ 전체 텍스트 추출
full_text = hwp.get_text()
print(f" ✔ 텍스트 추출 완료: {len(full_text)}자")
# ④ 텍스트 파일로 저장
Path(OUTPUT_TXT).write_text(full_text, encoding="utf-8")
print(f" ✔ 저장 완료 → {OUTPUT_TXT}")
# ⑤ 한글 프로그램 종료
hwp.quit()
print(f"\n✅ 완료!")
3단계: 완성 코드 — 폴더 안 HWP를 PDF로 일괄 변환
여러 HWP 파일을 PDF로 한꺼번에 변환하는 코드입니다. 아래 코드를 hwp_to_pdf.py로 저장하세요.
from pyhwpx import Hwp
from pathlib import Path
# ① 설정
FOLDER_PATH = r"C:\Users\내이름\Desktop\HWP모음" # ← 변환할 HWP 폴더
OUTPUT_DIR = r"C:\Users\내이름\Desktop\PDF변환결과" # ← PDF 저장 폴더
output_dir = Path(OUTPUT_DIR)
output_dir.mkdir(exist_ok=True)
folder = Path(FOLDER_PATH)
hwp_files = sorted(folder.glob("*.hwp"))
print(f" 📂 변환할 파일: {len(hwp_files)}개")
# ② 한글 프로그램 한 번만 실행 (반복문 안에서 매번 실행하면 느림)
hwp = Hwp(visible=False)
success = 0
failed = 0
for file in hwp_files:
try:
hwp.open(str(file))
pdf_path = output_dir / (file.stem + ".pdf")
hwp.save_as(str(pdf_path), format="PDF")
print(f" ✔ {file.name} → {pdf_path.name}")
success += 1
except Exception as e:
print(f" ✘ {file.name} 변환 실패: {e}")
failed += 1
# ③ 한글 프로그램 종료
hwp.quit()
print(f"\n✅ 완료! 성공: {success}개 / 실패: {failed}개 → {OUTPUT_DIR}")
4단계: 실행 방법
텍스트 추출:
- 코드 ① 설정의
HWP_PATH와 OUTPUT_TXT 경로를 입력합니다.
- 터미널에서 실행합니다:
python hwp_extract.py
PDF 일괄 변환:
python hwp_to_pdf.py
PDF 변환 정상 실행 시 터미널에 이렇게 출력됩니다:
📂 변환할 파일: 5개
✔ 공문_1월.hwp → 공문_1월.pdf
✔ 공문_2월.hwp → 공문_2월.pdf
✔ 견적서_A사.hwp → 견적서_A사.pdf
✔ 견적서_B사.hwp → 견적서_B사.pdf
✔ 안내문.hwp → 안내문.pdf
✅ 완료! 성공: 5개 / 실패: 0개 → C:\Users\내이름\Desktop\PDF변환결과
5단계: 자주 발생하는 오류와 해결법
오류 1: ModuleNotFoundError 또는 한글 프로그램 연결 실패
PC에 한글 프로그램이 설치되지 않은 경우입니다. 한글과컴퓨터 공식 사이트에서 한글 프로그램을 먼저 설치해야 합니다. 평가판으로도 자동화 기능은 대부분 동작합니다.
오류 2: 보안 모듈 관련 오류 또는 매크로 경고 팝업
한글의 보안 설정 때문에 자동화 실행 시 경고가 뜰 수 있습니다. 한글 프로그램에서 도구 → 환경 설정 → 보안 메뉴에서 매크로 보안 수준을 조정하거나, pyhwpx의 보안 모듈 등록 기능을 사용하세요. 라이브러리 공식 문서의 보안 설정 안내를 참고하면 도움이 됩니다.
오류 3: 변환 중 한글 프로그램이 멈춤
파일이 손상되었거나 매우 무거운 경우 발생할 수 있습니다. 작업 관리자에서 Hwp.exe 프로세스를 강제 종료하고, 문제가 된 파일을 건너뛰도록 try/except 처리를 활용하세요. 코드에 이미 포함되어 있습니다.
응용: 특정 문서에서 키워드 검색해서 위치 찾기
HWP 문서 안에서 특정 단어가 몇 번 나오는지, 어느 부분에 있는지 확인할 수 있습니다.
SEARCH_KEYWORD = "계약 기간" # ← 찾을 단어
full_text = hwp.get_text()
count = full_text.count(SEARCH_KEYWORD)
print(f" '{SEARCH_KEYWORD}' 검색 결과: {count}회 발견")
# 키워드 주변 50자씩 출력
import re
for match in re.finditer(SEARCH_KEYWORD, full_text):
start = max(0, match.start() - 30)
end = min(len(full_text), match.end() + 30)
print(f" ...{full_text[start:end]}...")
💡 이전 게시글과 결합하면: PDF 자동 병합 편과 결합하면 HWP에서 변환한 PDF들을 하나로 합칠 수 있고, 이메일 자동 발송 편과 결합하면 변환된 PDF를 자동으로 발송하는 것도 가능합니다.
핵심 요약
- 필수 조건: PC에 한글(HWP) 프로그램 설치 필수
- 준비물: Python + pyhwpx 설치 (pip install pyhwpx)
- 텍스트 추출: HWP_PATH, OUTPUT_TXT 설정 후 hwp_extract.py 실행
- PDF 변환: FOLDER_PATH, OUTPUT_DIR 설정 후 hwp_to_pdf.py 실행
- 결과: HWP 내용 텍스트 추출 또는 폴더 단위 PDF 일괄 변환
이 코드를 응용하면 HWP를 워드(.docx)로 변환하거나, 여러 HWP의 특정 표 데이터만 추출해 엑셀로 정리하는 것도 가능합니다.
