MarkItDown

PDF·Office·이미지·웹 콘텐츠를 LLM 친화 Markdown으로 바꾸는 Microsoft 변환 도구

pip install 'markitdown[all]'

Microsoft가 공개한 Python 기반 문서 변환 도구입니다. PDF, PowerPoint, Word, Excel, 이미지, 오디오, HTML, CSV/JSON/XML, ZIP, YouTube URL, EPUB 등을 Markdown으로 바꿔 LLM과 텍스트 분석 파이프라인에 넣기 쉽게 만듭니다. 고충실도 레이아웃 재현보다 구조와 텍스트 보존에 초점을 둡니다.

판단

이럴 때 씁니다

  • PDF, Office 문서, HTML, 이미지 메타데이터 같은 파일을 LLM 입력용 Markdown으로 표준화하고 싶을 때.
  • 에이전트에게 파일 원문을 그대로 주기보다 토큰 효율적인 텍스트 구조로 먼저 정리하고 싶을 때.
  • 문서 파이프라인에서 CLI와 Python API를 함께 쓰고 싶을 때.
  • 포맷별 선택 의존성으로 배포 크기와 기능 범위를 조절해야 할 때.

이럴 땐 쓰지 마세요

  • 원본 레이아웃을 픽셀 수준으로 보존해야 하는 전자문서 변환에는 맞지 않습니다.
  • 문서 사이의 관계, 코드 심볼 관계, 지식 그래프 질의가 목적이면 Graphify 같은 후단 도구가 필요합니다.
  • 이미 검색 가능한 웹 문서나 라이브러리 문서만 최신으로 주입하려는 목적이면 Context7 같은 MCP가 더 단순합니다.
  • 모든 포맷을 한 서버에 넣기 어렵다면 `[all]` 대신 필요한 extra를 좁혀야 합니다.

차별점

  • PDF·Office·이미지·오디오·HTML·텍스트 포맷·ZIP·YouTube URL까지 한 CLI와 Python API에서 Markdown으로 변환합니다.
  • 출력 목표가 사람이 보는 완벽한 레이아웃이 아니라 LLM이 읽기 쉬운 Markdown 구조입니다. 제목, 목록, 표, 링크 같은 문서 구조 보존을 우선합니다.
  • 선택 의존성을 `[pdf, docx, pptx]`처럼 포맷별로 설치할 수 있어 배포 환경의 무게를 조절할 수 있습니다.
  • 플러그인 시스템을 제공하고 `#markitdown-plugin` 생태계를 열어 둡니다. 기본 변환기 밖의 OCR 같은 확장 경로가 있습니다.

워크플로

  1. 01가상환경을 만들고 Python 3.10 이상을 확인합니다.
  2. 02`pip install 'markitdown[all]'` 또는 필요한 포맷 extra만 골라 설치합니다.
  3. 03`markitdown input.pdf -o output.md`로 원본을 Markdown으로 변환합니다.
  4. 04변환된 Markdown을 Codex CLI, Claude Code, RAG 파이프라인, Graphify 같은 후속 단계에 넘깁니다.

주요 명령

명령설명
pip install 'markitdown[all]'전체 선택 의존성을 포함해 설치합니다
markitdown path-to-file.pdf > document.md파일을 Markdown으로 변환해 표준 출력으로 보냅니다
markitdown path-to-file.pdf -o document.md출력 파일을 지정해 변환합니다
markitdown --list-plugins설치된 MarkItDown 플러그인을 확인합니다

함정

설치 전에 확인하세요

  • Python 3.10 이상이 필요하고, README는 가상환경 사용을 권합니다.
  • `[all]`은 편하지만 여러 포맷 의존성을 한 번에 끌어옵니다. 서버·CI에는 필요한 포맷 extra만 설치하는 쪽이 가볍습니다.
  • 출력은 LLM/텍스트 분석용 Markdown입니다. 사람에게 보여줄 고충실도 문서 변환기나 디자인 복원기로 보면 기대가 어긋납니다.
  • 플러그인은 기본 비활성화입니다. 플러그인을 쓰려면 `--use-plugins`를 명시해야 합니다.

직접 써본 메모

MarkItDown은 “문서를 예쁘게 변환하는 도구”보다 “에이전트가 읽을 수 있게 정리하는 전처리기”로 보는 편이 정확합니다. README도 human-friendly 출력은 부차적이고, LLM과 텍스트 분석 파이프라인을 주 사용처로 둡니다. 그래서 PDF나 Office 파일을 그대로 컨텍스트에 던지는 흐름보다 결과가 예측 가능해집니다.

장점은 지원 포맷 폭입니다. PDF·PPTX·DOCX·XLSX뿐 아니라 이미지 메타데이터/OCR, 오디오 전사, YouTube URL, ZIP 순회까지 한 진입점으로 묶습니다. 파일 수집 단계가 뒤섞인 팀이라면 변환기를 여러 개 조합하는 비용을 줄일 수 있습니다.

한계도 명확합니다. Markdown은 레이아웃 보존 포맷이 아니고, `[all]` 설치는 환경을 무겁게 만들 수 있습니다. 운영 환경에서는 필요한 포맷 extra만 켜고, 변환 실패나 OCR 품질은 후속 검증 단계에서 잡는 구성이 맞습니다.

비교

Graphify가 코드·문서·이미지를 지식 그래프로 구워 질의하는 도구라면, MarkItDown은 원본 파일을 먼저 Markdown 텍스트로 평평하게 만드는 전처리 도구입니다. Context7처럼 최신 라이브러리 문서를 가져오는 MCP와도 다릅니다. 파일 묶음을 LLM 입력으로 정리하는 단계에는 MarkItDown이 더 직접적이고, 관계 탐색이나 코드 구조 질의에는 Graphify가 맞습니다.

최근 변경

v0.1.6에서 이미지·PDF 스캔 OCR, PDF 변환 메모리 증가 수정, 깊은 HTML 처리와 Azure Content Understanding 변환기가 추가됐다.

공식 변경 내역