파일과 오피스 문서를 마크다운으로 바꾸는 MarkItDown

MarkItDown

중요

MarkItDown은 현재 프로세스의 권한으로 I/O를 수행합니다. open()이나 requests.get()처럼 프로세스 자체가 접근할 수 있는 리소스에 접근합니다. 신뢰할 수 없는 환경에서는 입력을 정제하고, 사용 사례에 필요한 가장 좁은 convert_* 함수를 호출하세요(예: convert_stream() 또는 convert_local()). 자세한 내용은 문서의 보안 고려 사항 섹션을 참조하세요.

MarkItDown은 다양한 파일을 LLM 및 관련 텍스트 분석 파이프라인에서 사용할 수 있도록 Markdown으로 변환하는 가벼운 Python 유틸리티입니다. 이 목적에서 보면 textract와 가장 비슷하지만, 중요한 문서 구조와 내용을 Markdown으로 보존하는 데 중점을 둡니다(예: 제목, 목록, 표, 링크 등). 출력 결과는 종종 꽤 보기 좋고 사람이 읽기에도 친숙하지만, 텍스트 분석 도구가 소비하도록 만든 것이며, 사람이 직접 보기 위한 고충실도 문서 변환에는 최선의 선택이 아닐 수 있습니다.

MarkItDown은 현재 다음 형식의 변환을 지원합니다.

• PDF

• PowerPoint

• Word

• Excel

• 이미지(EXIF 메타데이터 및 OCR)

• 오디오(EXIF 메타데이터 및 음성 전사)

• HTML

• 텍스트 기반 형식(CSV, JSON, XML)

• ZIP 파일(내용을 순회)

• YouTube URL

• EPub

• ... 그리고 더 있습니다!

왜 Markdown인가?

Markdown은 거의 일반 텍스트와 같고 마크업이나 서식은 최소한이지만, 중요한 문서 구조를 표현하는 방법을 제공합니다. OpenAI의 GPT-4o 같은 주류 LLM은 Markdown을 기본적으로 " 말할 수 " 있으며, 종종 별도의 지시 없이도 응답에 Markdown을 포함합니다. 이는 이들이 방대한 Markdown 형식 텍스트로 학습되었고 이를 잘 이해한다는 뜻입니다. 부가적으로 Markdown 규칙은 토큰 효율도 매우 높습니다.

사전 요구 사항

MarkItDown은 Python 3.10부터 3.14까지를 요구합니다. 의존성 충돌을 피하려면 가상 환경을 사용하는 것이 좋습니다.

표준 Python 설치에서는 다음 명령으로 가상 환경을 만들고 활성화할 수 있습니다.

python -m venv .venv
source .venv/bin/activate

uv를 사용하는 경우 다음과 같이 가상 환경을 만들 수 있습니다.

uv venv --python=3.12 .venv
source .venv/bin/activate
# NOTE: Be sure to use 'uv pip install' rather than just 'pip install' to install packages in this virtual environment

Anaconda를 사용하는 경우 다음과 같이 가상 환경을 만들 수 있습니다.

conda create -n markitdown python=3.12
conda activate markitdown

설치

MarkItDown을 설치하려면 pip를 사용하세요: pip install 'markitdown[all]'. 또는 소스에서 설치할 수도 있습니다.

git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

사용법

명령줄

markitdown path-to-file.pdf > document.md

또는 -o를 사용해 출력 파일을 지정할 수 있습니다.

markitdown path-to-file.pdf -o document.md

콘텐츠를 파이프로 넘길 수도 있습니다.

cat path-to-file.pdf | markitdown

선택적 종속성

MarkItDown에는 다양한 파일 형식을 활성화하기 위한 선택적 종속성이 있습니다. 앞서 이 문서에서는 [all] 옵션으로 모든 선택적 종속성을 설치했습니다. 하지만 더 세밀하게 제어하기 위해 개별적으로 설치할 수도 있습니다. 예를 들어:

pip install 'markitdown[pdf, docx, pptx]'

이렇게 하면 PDF, DOCX, PPTX 파일에 필요한 종속성만 설치됩니다.

현재 사용할 수 있는 선택적 종속성은 다음과 같습니다.

• [all] 모든 선택적 종속성을 설치합니다

• [pptx] PowerPoint 파일용 종속성을 설치합니다

• [docx] Word 파일용 종속성을 설치합니다

• [xlsx] Excel 파일용 종속성을 설치합니다

• [xls] 이전 Excel 파일용 종속성을 설치합니다

• [pdf] PDF 파일용 종속성을 설치합니다

• [outlook] Outlook 메시지용 종속성을 설치합니다

• [az-doc-intel] Azure Document Intelligence용 종속성을 설치합니다

• [az-content-understanding] Azure Content Understanding용 종속성을 설치합니다

• [audio-transcription] wav 및 mp3 파일의 오디오 전사용 종속성을 설치합니다

• [youtube-transcription] YouTube 동영상 전사를 가져오기 위한 종속성을 설치합니다

플러그인

MarkItDown은 서드파티 플러그인도 지원합니다. 플러그인은 기본적으로 비활성화되어 있습니다. 설치된 플러그인을 나열하려면:

markitdown --list-plugins

플러그인을 활성화하려면 다음을 사용하세요:

markitdown --use-plugins path-to-file.pdf

사용 가능한 플러그인을 찾으려면 GitHub에서 해시태그 #markitdown-plugin을 검색하세요. 플러그인을 개발하려면 packages/markitdown-sample-plugin을 참고하세요.

markitdown-ocr 플러그인

markitdown-ocr 플러그인은 PDF, DOCX, PPTX, XLSX 변환기에 OCR 지원을 추가하며, LLM Vision을 사용해 포함된 이미지에서 텍스트를 추출합니다. MarkItDown이 이미 이미지 설명에 사용하는 것과 같은 llm_client / llm_model 패턴을 사용합니다. 추가적인 ML 라이브러리나 바이너리 종속성은 필요하지 않습니다.

설치:

pip install markitdown-ocr
pip install openai  # or any OpenAI-compatible client

사용법:

이미지 설명에 사용할 때와 동일한 llm_client와 llm_model을 전달하세요:

12345678910from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.markdown)

llm_client가 제공되지 않으면 플러그인은 여전히 로드되지만, OCR은 조용히 건너뛰고 대신 표준 내장 변환기가 사용됩니다.

자세한 문서는 packages/markitdown-ocr/README.md를 참고하세요.

Azure Content Understanding

Azure Content Understanding은 구조화된 필드 추출(YAML front matter), 멀티모달 지원(문서, 이미지, 오디오, 비디오), 그리고 구성 가능한 분석기를 통해 더 높은 품질의 변환을 제공합니다.

설치: pip install 'markitdown[az-content-understanding]'

Content Understanding을 사용해야 하는 경우

Content Understanding은 내장 변환기나 Document Intelligence 변환기로는 제공되지 않는 기능이 필요할 때 적합합니다.

• 오디오 및 비디오 파일 — CU는 비디오에 대한 유일한 옵션이며, 오디오에 대해서도 더 높은 품질의 클라우드 옵션입니다. 내장 변환기는 비디오를 지원하지 않으며 오디오는 기본적인 전사만 제공합니다.

• 구조화된 필드 추출 — 사전 구축 또는 사용자 지정 구축 분석기는 인보이스 금액, 영수증 날짜, 계약 조항 같은 도메인별 필드를 YAML front matter로 직렬화해 추출합니다. 내장 기능도 Doc Intel 통합도 필드를 노출하지 않습니다.

• 더 높은 품질의 문서 추출 — 스캔된 PDF, 복잡한 표, 여러 페이지 문서에 대한 클라우드 기반 레이아웃 분석과 OCR.

• 모든 모달리티를 위한 단일 API — 하나의 cu_endpoint로 문서, 이미지, 오디오, 비디오를 처리하며 분석기 라우팅도 자동으로 수행합니다.

CLI:

markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"

엔드포인트는 환경에 한 번만 설정할 수도 있으므로, 호출자는 --use-cu만 있으면 됩니다:

export MARKITDOWN_CU_ENDPOINT="<content_understanding_endpoint>"
markitdown path-to-file.pdf --use-cu

Python API:

12345678from markitdown import MarkItDown

# Zero-config — auto-selects analyzer per file type
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf")   # documents → prebuilt-documentSearch
result = md.convert("meeting.mp4")  # video → prebuilt-videoSearch
result = md.convert("call.wav")     # audio → prebuilt-audioSearch
print(result.markdown)

사용자 지정 분석기를 사용하는 경우(도메인별 필드 추출용):

123456789101112131415md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_analyzer_id="my-invoice-analyzer",
)
result = md.convert("invoice.pdf")
print(result.markdown)
# Output includes YAML front matter with extracted fields:
# ---
# contentType: document
# fields:
#   VendorName: CONTOSO LTD.
#   InvoiceDate: '2019-11-15'
# ---
# 
# ...

cu_analyzer_id가 설정되면, 변환기는 분석기의 모달리티에 따라 호환되는 파일 형식에 자동으로 범위를 제한합니다. 호환되지 않는 형식(예: 문서 분석기로 오디오 파일 처리)은 기본 사전 구축 분석기로 자동 라우팅됩니다.

비용 안내: convert() 호출이 CU로 라우팅되는 형식일 때마다 Azure API 호출 요금이 부과됩니다. cu_file_types를 사용해 어떤 형식이 CU로 라우팅될지 제한하세요:

123456from markitdown.converters import ContentUnderstandingFileType

md = MarkItDown(
    cu_endpoint="<content_understanding_endpoint>",
    cu_file_types=[ContentUnderstandingFileType.PDF],  # only PDFs use CU
)

Azure Content Understanding에 대한 더 자세한 정보는 여기에서 확인할 수 있습니다.

Azure Document Intelligence

Microsoft Document Intelligence를 변환에 사용하려면:

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

엔드포인트는 환경에 한 번만 설정할 수도 있으므로, 호출자는 -d만 있으면 됩니다:

export MARKITDOWN_DOCINTEL_ENDPOINT="<document_intelligence_endpoint>"
markitdown path-to-file.pdf -o document.md -d

Azure Document Intelligence 리소스를 설정하는 방법에 대한 자세한 정보는 여기에서 확인할 수 있습니다.

Python API

Python에서의 기본 사용법:

12345from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.markdown)

Python에서 Document Intelligence 변환:

12345from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.markdown)

LLM을 사용해 이미지 설명을 생성하려면(현재는 pptx와 이미지 파일만 지원), llm_client와 llm_model을 제공하세요:

1234567from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI(max_retries=5)
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.markdown)

max_retries는 재시도 가능한 오류에 대해 OpenAI 클라이언트가 자동으로 재시도하는 횟수를 제어합니다(기본값은 2입니다). 5로 설정하면 백오프를 포함해 최대 6번까지 시도합니다. OpenAI SDK 재시도 문서를 참조하세요.

어떤 시도든 성공하면 이미지 변환은 정상적으로 계속됩니다. 클라이언트가 재시도를 모두 소진한 뒤 오류를 발생시키거나, 재시도할 수 없는 오류를 만나면 MarkItDown은 적용 가능한 다른 변환기를 시도하고, 아무것도 성공하지 못한 경우에만 FileConversionException을 발생시킵니다.

Docker

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

기여하기

중요한 작업을 시작하기 전에 먼저 What to Contribute를 읽어 주세요. 이 문서는 이 저장소의 범위에 포함되는 내용과 포함되지 않는 내용을 설명합니다.

이 프로젝트는 기여와 제안을 환영합니다. 대부분의 기여에는 Contributor License Agreement(CLA)에 동의해야 하며, 이를 통해 귀하가 기여물에 대한 권리를 실제로 보유하고 있고, 그 권리를 우리에게 사용 허가할 수 있음을 선언하게 됩니다. 자세한 내용은 https://cla.opensource.microsoft.com를 방문하세요.

풀 리퀘스트를 제출하면 CLA bot이 자동으로 CLA 제출이 필요한지 판단하고 PR에 적절한 표시를 추가합니다(예: 상태 확인, 댓글). bot이 제공하는 안내를 따르면 됩니다. 이 작업은 우리 CLA를 사용하는 모든 저장소를 통틀어 한 번만 수행하면 됩니다.

이 프로젝트는 Microsoft Open Source Code of Conduct를 채택했습니다. 자세한 내용은 Code of Conduct FAQ를 참조하거나, 추가 질문이나 의견이 있으면 opencode@microsoft.com으로 문의하세요.

기여할 수 있는 내용

MarkItDown은 LLM 및 관련 텍스트 분석 파이프라인에서 사용하기 위해 파일을 Markdown으로 변환하는 Python 유틸리티입니다. 이 저장소는 최종 사용자용 애플리케이션이 아니라, 다른 시스템에 통합할 수 있는 Python 라이브러리를 제공하는 것을 목적으로 합니다.

범위 내

• 기존 변환기의 충실도 향상(새 형식은 신중하게 추가됩니다. 특히 새로운 종속성이 생기는 경우에는 더욱 그렇습니다. 대부분의 경우 서드파티 플러그인을 통해 새 형식을 더 잘 지원할 수 있습니다.)

• 버그 수정, 성능 개선, 보안 수정

• markitdown 명령줄 인터페이스

• markitdown-mcp 패키지

• 테스트, 문서, 개발자 도구

범위 밖

다음과 같은 추가 애플리케이션, 서비스, 서버는 수용할 수 없습니다.

• 웹 서버, REST 또는 HTTP API, 그리고 호스팅된 변환 서비스

• 웹 프런트엔드 및 브라우저 기반 사용자 인터페이스

• 데스크톱 및 모바일 애플리케이션(PyQt, PySide, Tkinter, Electron, Flutter 등)

이런 프로젝트들은 정말 유용하며, 거절하기보다는 잘 성장하길 바랍니다. MarkItDown용 웹 서비스, API 또는 그래픽 애플리케이션을 제공하고 싶다면, markitdown from PyPI에 의존하는 별도의 패키지나 프로젝트로 유지해 주세요.

이 저장소를 변경하지 않고 MarkItDown 확장하기

MarkItDown은 서드파티 플러그인을 지원하므로, 새 형식에 대한 지원은 이 저장소와 독립적으로 게시하고 설치할 수 있습니다:

markitdown --list-plugins
markitdown --use-plugins path-to-file.pdf

시작하려면 packages/markitdown-sample-plugin을 참고하고, 다른 사람들이 찾을 수 있도록 저장소에 #markitdown-plugin 태그를 달아 주세요.

기여 방법

이슈를 살펴보거나 PR 리뷰를 도와주시면 됩니다. 또한 커뮤니티 기여를 돕기 위해 일부 이슈에는 'open for contribution', 일부 PR에는 'open for reviewing' 라벨을 붙였습니다. 이 라벨은 제안 사항이며, 위에서 설명한 범위 안의 기여는 언제나 환영합니다.

테스트 및 검사 실행

• MarkItDown 패키지로 이동합니다:

cd packages/markitdown

• 환경에 hatch를 설치한 뒤 테스트를 실행합니다:

pip install hatch  # Other ways of installing hatch: https://hatch.pypa.io/dev/install/
hatch shell
hatch test

(대안) 필요한 모든 종속성이 설치된 Devcontainer를 사용합니다:

# Reopen the project in Devcontainer and run:
hatch test

• PR을 제출하기 전에 pre-commit 검사를 실행합니다: pre-commit run --all-files

보안 고려 사항

MarkItDown은 현재 프로세스의 권한으로 I/O를 수행합니다. open()이나 requests.get()처럼, 프로세스 자체가 접근할 수 있는 리소스에 접근합니다.

입력을 안전하게 처리하세요: 신뢰할 수 없는 입력을 MarkItDown에 직접 전달하지 마세요. 입력의 일부라도 호스팅되거나 서버 측 애플리케이션처럼 신뢰할 수 없는 사용자나 시스템이 제어할 수 있다면, MarkItDown을 호출하기 전에 반드시 검증하고 제한해야 합니다. 환경에 따라 파일 경로 제한, URI 스킴 및 네트워크 대상 제한, 그리고 private, loopback, link-local, 또는 메타데이터 서비스 주소에 대한 접근 차단이 포함될 수 있습니다.

필요한 변환 메서드만 호출하세요: 사용 사례에 맞는 가장 좁은 범위의 변환 API를 우선 사용하세요. MarkItDown의 convert() 메서드는 의도적으로 허용 범위가 넓으며 로컬 파일, 원격 URI, 바이트 스트림을 모두 처리할 수 있습니다. 애플리케이션이 로컬 파일만 읽으면 된다면 대신 convert_local()을 호출하세요. URI 가져오기를 더 세밀하게 제어해야 한다면 requests.get()을 직접 호출하고 응답 객체를 convert_response()에 전달하세요. 최대한의 제어가 필요하다면 변환할 입력에 대한 스트림을 열고 convert_stream()을 호출하세요.

상표

이 프로젝트에는 프로젝트, 제품 또는 서비스의 상표나 로고가 포함될 수 있습니다. Microsoft 상표나 로고의 승인된 사용은 Microsoft 상표 및 브랜드 가이드라인 을 따라야 합니다. 이 프로젝트를 수정한 버전에서 Microsoft 상표나 로고를 사용하는 경우 혼동을 일으키거나 Microsoft의 후원으로 오해되게 해서는 안 됩니다. 제3자 상표나 로고의 사용은 해당 제3자의 정책을 따라야 합니다.

출처

• 원문: https://github.com/microsoft/markitdown (2026-10-07 · github.com)