PyMuPDF Layout 튜토리얼 — 시작하기

안녕하세요, 이파피루스입니다.

이번 포스팅은 PyMuPDF Layout을 사용하는 가장 기초적인 워크플로우를 설명합니다.
Python과 커맨드라인 사용 경험, PyPI 패키지 설치 경험이 있으면 쉽게 따라올 수 있어요.

---

1️⃣ 설치하기

먼저 필요한 패키지를 설치합니다. 터미널에서 아래 명령어를 실행하세요:

pip install pymupdf-layout
pip install pymupdf4llm

PyMuPDF Layout은 레이아웃을 감지/분석하는 역할을 하고,
PyMuPDF4LLM은 그 결과를 Markdown, JSON, 텍스트 같은 출력 형태로 변환하는 역할을 합니다.

---

2️⃣ PyMuPDF Layout 주요 기능

PyMuPDF Layout으로 할 수 있는 일은 크게 두 가지입니다:

1. 문서에서 구조화된 데이터(텍스트, 표, 리스트 등)을 추출
   → Markdown, JSON, plain text로 저장 가능
2. 문서 파싱 시 헤더와 푸터를 포함하거나 제외할 수 있음
   → 반복적인 헤더/푸터 같은 불필요 요소도 쉽게 무시 가능

---

3️⃣ Python 코드로 PDF 열기

코드를 작성해서 실제 문서를 열어보겠습니다.

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

🚨 주의:
pymupdf.layout 은 반드시 PyMuPDF4LLM을 임포트하기 전에 먼저 불러와야 합니다.
그렇지 않으면 레이아웃 기능이 활성화되지 않고 그냥 일반 PyMuPDF4LLM만 동작합니다.

---

4️⃣ 구조화된 데이터 추출하기

라이브러리가 활성화된 상태에서 문서를 열었으면 이제 구조화 데이터를 뽑아봅시다.
PyMuPDF Layout은 내부적으로 휴리스틱 + 머신러닝을 결합해서 더 정확한 추출 결과를 제공합니다.

🟩 Markdown으로 추출

md = pymupdf4llm.to_markdown(doc)

🟦 JSON으로 추출

json = pymupdf4llm.to_json(doc)

⬛ Plain Text로 추출

txt = pymupdf4llm.to_text(doc)

5️⃣ 결과를 파일로 저장하기

추출한 데이터는 파일로 저장할 수 있습니다. 예를 들어 Markdown 포맷으로 저장하려면 이렇게 씁니다:

from pathlib import Path
suffix = ".md" # or “.json” or “.txt”
Path(doc.name).with_suffix(suffix).write_bytes(md.encode())

이렇게 하면 sample.pdf 옆에
sample.md, sample.json, sample.txt 같은 파일이 생성됩니다.

---

6️⃣ 헤더 & 푸터 처리

많은 문서에서는 각 페이지마다 반복되는 헤더/푸터가 있을 수 있습니다.
예: 문서 제목, 로고, 페이지 번호 등. 이런 요소들은 추출 시 필요 없을 때가 많죠.

PyMuPDF Layout은 이런 반복 요소를 자동으로 감지하고 제거할 수 있습니다.
API 호출 시 옵션으로 끌 수도 있죠:

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

참고: JSON 포맷은 항상 모든 페이지 데이터를 포함 하는 목적이기 때문에 헤더·푸터 제거 옵션이 적용되지 않습니다.

---

7️⃣ 추가 기능

🗂 확장: Office 문서 지원

PyMuPDF Pro와 함께 사용하면 Office 문서(예: DOCX)도 처리할 수 있습니다.
이 방법은 PyMuPDF Pro를 unlock 한 뒤 Layout을 활성화하면 됩니다:

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

이제 DOCX도 Markdown으로 변환 가능합니다.

---

8️⃣ OCR 지원

PyMuPDF Layout은 페이지에 OCR이 필요하다고 판단되면 자동으로 Tesseract-OCR을 실행해 처리합니다.
만약 해당 모듈이 설치되어 있지 않으면 그 단계는 건너뜁니다.

---

9️⃣ 선택 페이지 추출

기본적으로는 PDF의 모든 페이지가 처리됩니다.
다만 큰 문서의 일부 페이지만 필요할 때도 있죠.
그럴 땐 to_markdown, to_json, to_text 호출에 pages 옵션을 줄 수 있습니다:

• # 한 페이지만
  pymupdf4llm.to_markdown(doc, pages=3)
• # 여러 페이지만
  pymupdf4llm.to_markdown(doc, pages=[1, 3, 5])

페이지 번호는 0 기반 인덱스로 지정합니다.

 

마무리

마지막으로 전체 프로세스를 하나의 스크립트로 묶어서 CLI에서 실행할 수도 있습니다:

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라는 이름으로 저장하고, 불러올 PDF 파일(sample.pdf)과 같은 폴더에 두겠습니다.
그러면 폴더 구조는 다음과 같습니다:

test-layout.py
sample.pdf

이제 위 코드를 커맨드라인(터미널)에서 실행하려면 다음과 같이 입력하면 됩니다:

python test-layout.py sample.pdf

이 명령어는 방금 만든 Python 스크립트를 지정한 문서와 함께 실행하겠다는 뜻입니다.
다른 문서를 처리하고 싶다면 파일명만 바꿔서 다시 실행하면 됩니다.

실행이 끝나면, 폴더에는 변환된 출력 파일들이 생성되어 있고 구조는 다음과 같습니다:

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

---

🎉 Happy Coding! 🙂

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