'PyMuPDF Pro' PyMuPDF Layout 시작하기!

이 블로그 포스트에서는 PyMuPDF Pro에 포함되어 있는 PyMuPDF Layout을 어떻게 시작하는지와, 무엇을 할 수 있는지 단계별로 설명합니다.
Python과 명령줄(Command Line)에 대한 기본 지식, 그리고 PyPI(Python Package Index)에서 패키지를 설치해본 경험이 필요합니다.

---

PyMuPDF Layout 설치하기

먼저 PyPI에서 필요한 PyMuPDF Pro패키지를 설치해야 합니다.

명령줄 또는 터미널을 열고 다음을 실행하세요:

pip install pymupdf-layout
pip install pymupdf4llm

요약하자면, PyMuPDF Layout은 추출해야 할 문서 레이아웃을 감지하는 역할,
그리고 PyMuPDF4LLM은 결과물을 Markdown/JSON/텍스트로 출력하는 역할을 담당합니다.

---

📌 PyMuPDF Layout으로 할 수 있는 일

PyMuPDF Layout으로는 아래 두 가지를 수행할 수 있습니다.

1. 문서에서 구조화된 데이터를 Markdown, JSON 또는 텍스트로 추출하기
2. 문서를 파싱할 때 헤더·푸터를 포함하거나 제외하기

이제 Python 코딩 환경을 설정하고 PDF를 열어본 뒤, 실제 기능을 확인해봅시다.

---

패키지 등록 및 PDF 열기

먼저 라이브러리를 임포트하고 샘플 문서를 엽니다:

import pymupdf.layout
import pymupdf4llm
doc = pymupdf.open("sample.pdf")

주의!
위 코드에서 pymupdf.layout 은 반드시 먼저 임포트해야 합니다.
그래야 PyMuPDF Pro의 레이아웃 기능이 활성화되어 PyMuPDF4LLM도 이를 사용할 수 있습니다.
첫 줄을 생략하면 일반 PyMuPDF4LLM이 실행되어 레이아웃 기능이 작동하지 않습니다!

 

---

📌 구조화 데이터 추출하기

PyMuPDF Layout을 활성화했고 문서도 불러왔으니, 이제 구조화 데이터를 추출해봅시다.
이 기능은 기존 PyMuPDF4LLM을 강화한 버전으로, 내부적으로 레이아웃 감지와 머신러닝을 결합하여 더 나은 결과를 제공합니다.

---

Markdown으로 추출

md = pymupdf4llm.to_markdown(doc)

---

JSON으로 추출

json = pymupdf4llm.to_json(doc)

---

일반 텍스트로 추출

txt = pymupdf4llm.to_text(doc)

---

결과물 파일로 저장하기

from pathlib import Path
suffix = ".md"  # 또는 ".json", ".txt"
Path(doc.name).with_suffix(suffix).write_bytes(md.encode())

---

📝 헤더 & 푸터 처리

많은 문서에는 페이지마다 반복되는 헤더/푸터가 포함되어 있으며,
이 정보는 문서 콘텐츠 추출 시 필요 없거나 반복적인 경우가 많습니다.

예)

• 로고
• 문서 제목
• 페이지 번호 등

PyMuPDF Layout은 이러한 전형적인 문서 요소를 감지하고 제거할 수 있습니다.

다음과 같이 API 호출 시 옵션을 조정하면 됩니다:

md = pymupdf4llm.to_markdown(doc, header=False, footer=False)
txt = pymupdf4llm.to_text(doc, header=False, footer=False)

주의!
JSON 출력은 항상 페이지 내 모든 데이터를 포함하는 것이 목적이므로헤더·푸터 제거 옵션이 적용되지 않습니다.

---

📌 기능 확장하기 — PyMuPDF Pro와 결합

PyMuPDF Layout은 PyMuPDF Pro와 함께 사용할 수 있으며,
이 경우 Office 문서(DOCX, XLSX, PPTX 등) 를 입력 파일로 사용할 수 있게 됩니다.

추가해야 할 것은 PyMuPDF Pro 임포트 및 unlock 호출뿐입니다:

import pymupdf.layout
import pymupdf.pro
import pymupdf4llm
pymupdf.pro.unlock()

이제 Office 파일도 자유롭게 변환할 수 있습니다:

md = pymupdf4llm.to_markdown("sample.docx")

---

🔍 OCR 지원

새로운 레이아웃 기반 PyMuPDF4LLM은
각 페이지에 OCR 수행이 필요한지 자동으로 판단합니다.

• 필요하다고 판단 → 내장된 Tesseract-OCR 모듈을 자동 실행
• 그렇지 않으면 OCR 생략

Tesseract가 시스템에 설치되어 있지 않다면 OCR은 수행되지 않습니다.

---

📄 페이지 부분 추출(Sub-Selecting Pages)

기본적으로 문서의 모든 페이지를 처리합니다.
하지만 매우 큰 문서라면 시간이 오래 걸릴 수 있습니다.

이때 특정 페이지만 선택하여 처리할 수 있습니다:

pages=n                  # 단일 페이지
pages=[1, 3, 5, 7]       # 특정 페이지 리스트 (0-based)

---

🧩 마무리 — 전체 스크립트 예제

아래는 모든 기능을 결합한 완성 스크립트입니다.
명령줄에서 파일명을 입력받아, 헤더/푸터 제거 후 Markdown / JSON / 텍스트 파일로 저장합니다.

import sys
from pathlib import Path

import pymupdf.layout
import pymupdf.pro
import pymupdf4llm
pymupdf.pro.unlock()

filename = sys.argv[1]
doc = pymupdf.open(filename)

md = pymupdf4llm.to_markdown(doc, header=False, footer=False)
json = pymupdf4llm.to_json(doc)
txt = pymupdf4llm.to_text(doc, header=False, footer=False)

Path(filename).with_suffix(".md").write_bytes(md.encode())
Path(filename).with_suffix(".json").write_bytes(json.encode())
Path(filename).with_suffix(".txt").write_bytes(txt.encode())

이 파일을 test-layout.py 라는 이름으로 저장하고,
변환할 문서(sample.pdf)와 같은 폴더에 두세요.

폴더 구성 예:

test-layout.py
sample.pdf

명령줄에서 다음과 같이 실행합니다:

python test-layout.py sample.pdf

그러면 같은 폴더에 다음 결과물이 생성됩니다:

test-layout.py
sample.pdf
sample.md
sample.json
sample.txt

---

🎉 Happy Coding! 🙂

앞으로, 다양하고 유익한 PyMuPDF Pro 튜토리얼로 찾아오겠습니다. 기대해주세요! 감사합니다 :)
PyMuPDF Pro 제품소개페이지 바로가기 >