Microsoft MarkItDown 사용법: PDF·Word·PPT·Excel을 Markdown으로 변환하는 방법

 오픈소스 실전 가이드

MarkItDown의 개념부터 설치, CLI와 Python API 사용법, RAG 파이프라인 적용 방법, 한계와 보안 주의사항까지 단계별로 설명합니다.

30초 핵심 요약

MarkItDown은 PDF와 Office 문서 등 여러 파일을 LLM이 처리하기 쉬운 Markdown으로 통합 변환하는 Python 라이브러리이자 CLI 도구입니다.

파일 형식마다 별도의 파서를 조합하는 대신 하나의 변환 인터페이스를 사용할 수 있어 RAG, 벡터 데이터베이스, 문서 검색, 요약 파이프라인의 입력 구조를 단순화할 수 있습니다.

이 글에서 확인할 내용

• MarkItDown이 어떤 문제를 해결하는지 이해합니다.
• 가상환경 구성과 패키지 설치 방법을 확인합니다.
• CLI와 Python API로 문서를 변환하는 방법을 익힙니다.
• 변환 결과를 RAG와 벡터DB에 연결하는 흐름을 살펴봅니다.
• 지원 범위, 한계, 보안 검토 항목을 확인합니다.

목차

1. MarkItDown은 어떤 도구인가?
2. MarkItDown을 설치하고 문서를 변환하는 방법
3. RAG와 LLM 파이프라인에 적용하는 방법
4. 장점과 한계, 보안 주의사항
5. 자주 묻는 질문

MarkItDown은 어떤 도구인가?

MarkItDown은 Microsoft가 공개한 파일·문서 Markdown 변환 도구입니다. PDF, Word, Excel, PowerPoint처럼 서로 구조가 다른 입력을 하나의 인터페이스로 처리하고, 제목·목록·표·링크 등 중요한 문서 구조를 가능한 범위에서 Markdown으로 표현합니다.

이 도구의 핵심 목적은 원본 문서를 시각적으로 똑같이 복원하는 것이 아닙니다. 문서 내용을 LLM, 검색 시스템, 텍스트 분석 도구가 처리하기 쉬운 구조로 바꾸는 데 초점을 둡니다.

쉽게 설명하면

MarkItDown은 여러 종류의 문서를 Markdown이라는 공통 언어로 번역하는 통역기입니다. 변환된 결과를 GPT에 전달하거나, 문서 조각으로 나눠 벡터DB에 저장하거나, 검색 가능한 사내 지식베이스를 만드는 데 사용할 수 있습니다.

어떤 형식을 변환할 수 있나?

공식 저장소에서 안내하는 주요 지원 범위는 다음과 같습니다. 실제 변환 기능은 설치한 선택형 의존성, 파일 내부 구조, OCR 또는 외부 서비스 사용 여부에 따라 달라질 수 있습니다.

입력 유형	주요 형식	변환 결과 예시
Office 문서	DOCX, XLSX, XLS, PPTX	제목, 문단, 시트, 표, 슬라이드 텍스트
문서·웹	PDF, HTML, EPUB	본문, 링크, 표, 문서 구조
텍스트 데이터	CSV, JSON, XML	표 또는 계층형 텍스트
미디어	이미지, 오디오, YouTube URL	메타데이터, OCR, 음성 전사
압축 파일	ZIP	내부 파일을 순회한 변환 내용

기존 문서 파서 조합과 무엇이 다른가?

기존에는 Word에는 python-docx, Excel에는 openpyxl, PowerPoint에는 python-pptx, PDF에는 별도의 PDF 파서를 사용하는 식으로 파일 형식마다 코드를 나눠 작성하는 경우가 많았습니다.

기존 방식

파일 확장자 확인 → 형식별 라이브러리 선택 → 서로 다른 API 호출 → 출력 구조 통일 → Markdown 후처리

MarkItDown 방식

입력 전달 → 파일 유형 판별 → 적절한 변환기 선택 → 공통 Markdown 결과 반환

따라서 개발자는 파일 형식별 분기와 후처리를 완전히 없애지는 못하더라도, 문서 수집 파이프라인의 기본 인터페이스를 상당히 단순화할 수 있습니다.

MarkItDown을 설치하고 문서를 변환하는 방법

Python 3.10 이상의 가상환경을 만든 뒤 필요한 변환 기능을 선택해 설치하면 됩니다. 여러 형식을 테스트하려면 전체 기능을 설치하고, 운영 환경에서는 필요한 변환기만 선택하는 방식이 효율적입니다.

1단계: Python 가상환경 만들기

프로젝트마다 독립된 가상환경을 사용하면 문서 변환 라이브러리의 의존성 충돌을 줄일 수 있습니다.

python -m venv .venv

source .venv/bin/activate

Windows 명령 프롬프트에서는 다음과 같이 활성화할 수 있습니다.

python -m venv .venv

.venv\Scripts\activate

2단계: MarkItDown 설치하기

PDF, Word, Excel, PowerPoint 등 여러 형식을 한 번에 시험하려면 전체 선택 기능을 설치합니다.

pip install "markitdown[all]"

필요한 형식만 사용할 때는 선택형 의존성을 지정할 수 있습니다.

pip install "markitdown[pdf,docx,pptx,xlsx]"

설치 전략

개인 테스트 환경에서는 all 옵션이 편리합니다. 배포용 컨테이너나 서버에서는 실제로 처리할 형식만 설치하면 이미지 크기와 불필요한 의존성을 줄일 수 있습니다.

3단계: CLI로 파일 변환하기

한두 개의 파일을 빠르게 변환하거나 셸 스크립트에서 사용할 때는 CLI가 가장 간단합니다.

markitdown report.pdf -o report.md

표준 출력을 파일로 리다이렉션하는 방식도 사용할 수 있습니다.

markitdown presentation.pptx > presentation.md

Word와 Excel도 같은 명령 구조로 변환합니다.

markitdown meeting.docx -o meeting.md

markitdown sales.xlsx -o sales.md

4단계: Python API로 변환하기

애플리케이션 코드, 배치 작업, 업로드 API 또는 RAG 수집기에서는 Python API를 사용하는 편이 좋습니다.

from markitdown import MarkItDown

 

md = MarkItDown(enable_plugins=False)

result = md.convert("report.docx")

markdown_text = result.text_content

 

print(markdown_text)

현재 공식 기본 사용 예시에서는 일반 변환 결과를 result.text_content로 읽습니다. 일부 추가 변환기나 최신 인터페이스 예시에서는 result.markdown이 사용될 수 있으므로, 설치 버전의 반환 객체와 공식 README를 함께 확인하는 것이 안전합니다.

5단계: 변환 결과를 파일로 저장하기

from pathlib import Path

from markitdown import MarkItDown

 

source_path = Path("report.docx")

output_path = source_path.with_suffix(".md")

 

converter = MarkItDown(enable_plugins=False)

result = converter.convert(str(source_path))

 

output_path.write_text(

    result.text_content,

    encoding="utf-8"

)

여러 파일을 일괄 변환하려면?

입력 폴더의 파일을 순회하면서 확장자별로 Markdown 파일을 생성할 수 있습니다.

from pathlib import Path

from markitdown import MarkItDown

 

input_dir = Path("documents")

output_dir = Path("markdown")

output_dir.mkdir(parents=True, exist_ok=True)

 

supported = {".pdf", ".docx", ".xlsx", ".pptx"}

converter = MarkItDown(enable_plugins=False)

 

for source in input_dir.iterdir():

    if not source.is_file() or source.suffix.lower() not in supported:

        continue

 

    try:

        result = converter.convert(str(source))

        target = output_dir / f"{source.stem}.md"

        target.write_text(result.text_content, encoding="utf-8")

        print(f"완료: {source.name}")

    except Exception as error:

        print(f"실패: {source.name} - {error}")

운영 환경에서 추가할 항목

• 최대 파일 크기와 처리 시간 제한
• 허용 확장자와 실제 MIME 유형 검증
• 실패 파일 격리와 오류 로그 저장
• 중복 파일 해시 확인
• 변환 결과 품질 검사와 재처리 기준

RAG와 LLM 파이프라인에 적용하는 방법

MarkItDown의 출력은 그대로 저장하는 것보다 정제, 분할, 메타데이터 추가 단계를 거쳐 RAG에 연결하는 것이 좋습니다. Markdown 변환은 문서 수집 파이프라인의 시작점이며, 검색 품질은 이후 처리 방식에도 크게 영향을 받습니다.

권장 문서 수집 흐름

1. 입력 검증: 파일 크기, 형식, 출처와 권한을 확인합니다.
2. Markdown 변환: MarkItDown으로 문서 구조를 공통 형식으로 바꿉니다.
3. 결과 정제: 반복 머리말, 바닥글, 빈 줄, 불필요한 기호를 정리합니다.
4. 문서 분할: 제목과 섹션 구조를 기준으로 검색 단위를 만듭니다.
5. 메타데이터 추가: 파일명, 부서, 작성일, 페이지, 권한 정보를 연결합니다.
6. 임베딩 생성: 각 문서 조각을 벡터로 변환합니다.
7. 벡터DB 저장: 원문, 벡터, 메타데이터를 함께 저장합니다.

변환 직후 어떤 품질 검사를 해야 하나?

파일이 오류 없이 변환됐다고 해서 검색용 데이터가 완성된 것은 아닙니다. 문서 유형별로 다음 항목을 점검해야 합니다.

문서 유형	확인할 항목	후처리 예시
PDF	읽기 순서, 표, 머리말, 스캔 여부	반복 영역 제거, OCR 검토
Word	제목 단계, 목록, 표, 각주	제목 기준 청킹
PowerPoint	슬라이드 순서, 도형 텍스트, 발표자 노트	슬라이드 번호 메타데이터 추가
Excel	시트명, 병합 셀, 수식, 넓은 표	시트별 분리, 표 설명 추가

Markdown은 어떻게 나누는 것이 좋은가?

글자 수만 기준으로 자르면 제목과 본문이 분리되거나 표가 중간에서 끊길 수 있습니다. 먼저 Markdown 제목을 기준으로 섹션을 나눈 뒤, 너무 긴 섹션만 추가로 분할하는 방식이 실무적으로 안정적입니다.

• 상위 제목을 문서 조각의 문맥으로 유지합니다.
• 목록과 표는 가능하면 하나의 조각에 포함합니다.
• 파일명과 페이지 또는 슬라이드 번호를 메타데이터로 저장합니다.
• 문서 접근 권한을 검색 필터에 사용할 수 있도록 보존합니다.
• 검색 평가 결과를 바탕으로 조각 크기와 중첩 범위를 조정합니다.

실제 활용 사례

사내 문서 검색

부서별 Word, PDF, PowerPoint 문서를 Markdown으로 통일한 뒤 권한 메타데이터와 함께 벡터DB에 저장합니다.

회의 자료 자동 요약

회의용 PPT와 회의록 DOCX를 Markdown으로 변환한 뒤 요약 프롬프트에 전달해 결정 사항과 후속 업무를 추출합니다.

계약서 검색 시스템

계약서를 조항 단위로 나누고 계약명, 당사자, 계약 기간, 보안 등급을 메타데이터로 저장해 검색 범위를 제한합니다.

AI 에이전트 문서 입력

에이전트가 받은 문서를 공통 Markdown 형식으로 변환한 뒤 요약, 분류, 정보 추출 또는 질의응답 도구에 연결합니다.

장점과 한계, 보안 주의사항

MarkItDown의 가장 큰 장점은 여러 문서 형식을 하나의 Markdown 변환 단계로 표준화한다는 점입니다. 다만 원본 레이아웃의 완벽한 재현, 복잡한 차트 해석, 모든 PDF의 정확한 표 추출까지 자동으로 보장하는 도구는 아닙니다.

장점	한계
여러 파일 형식을 공통 API로 처리	복잡한 원본 레이아웃은 동일하게 재현되지 않을 수 있음
Markdown 구조를 활용한 LLM 입력 가능	스캔 PDF와 이미지 텍스트는 OCR 설정이 필요할 수 있음
CLI와 Python API를 모두 지원	도표와 차트의 시각적 의미가 손실될 수 있음
필요한 변환기만 선택 설치 가능	문서별 품질 검수와 후처리는 여전히 필요함
플러그인 방식으로 기능 확장 가능	플러그인 활성화 시 코드와 권한을 별도로 검토해야 함

비슷한 프로젝트와 어떻게 다른가?

프로젝트의 우열보다 출력 목적과 운영 요구사항을 기준으로 선택해야 합니다. MarkItDown은 LLM용 Markdown 변환을 간단하게 시작하려는 경우에 적합합니다.

프로젝트	중심 특징	검토하기 좋은 상황
MarkItDown	여러 형식을 Markdown으로 통합 변환	LLM·RAG 전처리를 빠르게 구성할 때
Docling	문서 구조와 레이아웃 분석 중심	복잡한 문서 구조를 세밀하게 다룰 때
textract	다양한 파일에서 텍스트 추출	구조보다 일반 텍스트 추출이 중요할 때
Unstructured	문서 요소 분류와 파이프라인 구성	복잡한 엔터프라이즈 수집 흐름을 설계할 때

신뢰할 수 없는 파일을 처리할 때 무엇을 주의해야 하나?

MarkItDown은 현재 프로세스가 가진 권한으로 파일과 URI 등의 리소스에 접근할 수 있습니다. 따라서 외부 사용자가 업로드한 파일이나 주소를 바로 변환하도록 허용하면 안 됩니다.

보안 체크리스트

• 업로드 파일의 확장자와 실제 MIME 유형을 함께 확인합니다.
• 허용된 디렉터리 밖의 경로에 접근하지 못하도록 제한합니다.
• URL 변환을 허용할 경우 내부망 주소와 로컬 주소 접근을 차단합니다.
• 파일 크기, 압축 해제 크기, 처리 시간과 메모리를 제한합니다.
• 변환 작업을 최소 권한의 격리된 프로세스나 컨테이너에서 실행합니다.
• 필요한 범위에 맞는 convert 계열 함수를 사용합니다.
• 서드파티 플러그인은 코드와 의존성을 검토한 뒤 활성화합니다.

최신 버전에서 확인할 변화

2026년 7월 15일 기준 PyPI 최신 안정 버전은 0.1.6입니다. 해당 릴리스에는 임베디드 이미지와 스캔 PDF를 위한 OCR 계층 서비스, PDF 변환 과정의 메모리 증가 개선, 깊게 중첩된 HTML 처리 보완, 보안 안내 명확화, Azure Content Understanding 변환기 추가 등이 포함됐습니다.

버전 업그레이드 전 확인

운영 중인 코드에서는 반환 속성, 선택형 의존성, 플러그인 호환성, 변환 결과 차이를 테스트한 뒤 버전을 고정하는 것이 좋습니다. 특히 문서 검색 시스템은 변환 결과 변화가 청크와 임베딩 결과에 영향을 줄 수 있습니다.

핵심 정리

MarkItDown은 단순한 파일 변환 유틸리티보다 LLM 애플리케이션의 입력 계층을 표준화하는 도구로 이해하는 것이 정확합니다. 문서 형식별 파서를 직접 관리하는 부담을 줄일 수 있지만, 실제 서비스에서는 입력 검증, 변환 품질 평가, 청킹, 메타데이터와 접근 권한 관리가 함께 필요합니다.

자주 묻는 질문

MarkItDown 설치와 문서 변환을 시작할 때 자주 확인하는 질문을 정리했습니다.

MarkItDown은 무료로 사용할 수 있나요?

네. MarkItDown은 Microsoft가 MIT 라이선스로 공개한 오픈소스 프로젝트입니다. 다만 OCR, 음성 전사, Azure 서비스 또는 외부 LLM API를 연결하면 해당 서비스의 사용 비용과 이용 조건이 별도로 적용될 수 있습니다.

MarkItDown으로 스캔 PDF도 변환할 수 있나요?

스캔 PDF는 일반 텍스트 PDF와 처리 방식이 다릅니다. 이미지로만 구성된 PDF에서 글자를 추출하려면 OCR 기능이나 관련 플러그인 또는 외부 문서 분석 서비스를 설정해야 하며, 원본 이미지 품질에 따라 결과를 검수해야 합니다.

MarkItDown 변환 결과를 바로 벡터DB에 저장해도 되나요?

바로 저장할 수는 있지만 변환 품질 검사와 후처리를 거치는 것이 좋습니다. 반복 머리말과 바닥글을 제거하고, 제목 구조를 기준으로 문서를 나누며, 파일명·페이지·권한 같은 메타데이터를 추가한 뒤 임베딩하는 방식이 검색 품질 관리에 유리합니다.

MarkItDown과 Docling 중 어떤 도구를 선택해야 하나요?

여러 파일을 Markdown으로 간단히 통합 변환하려면 MarkItDown을 먼저 검토할 수 있습니다. 복잡한 페이지 레이아웃과 문서 구조를 더 세밀하게 분석해야 한다면 Docling을 함께 비교하고, 실제 업무 문서로 변환 정확도와 처리 속도를 테스트해 선택하는 것이 좋습니다.

MarkItDown을 운영 서버에서 사용할 때 가장 중요한 보안 설정은 무엇인가요?

변환 프로세스의 접근 권한을 최소화하고 입력 범위를 제한하는 것이 중요합니다. 파일 경로, URL, MIME 유형, 파일 크기와 처리 시간을 검증하고, 외부 입력은 격리된 환경에서 처리하며, 필요한 변환 기능과 플러그인만 활성화해야 합니다.