Microsoft AutoGen 팀이 만든 오픈소스 Python 라이브러리다. PDF, Word, Excel, PowerPoint, 이미지, 오디오, YouTube URL까지 거의 모든 파일 형식을 Markdown으로 변환해준다. LLM은 Markdown을 가장 잘 이해하기 때문에, RAG 파이프라인이나 AI 분석 전처리 단계에서 바로 쓸 수 있다.
주요 특징 (Key Features)
① 압도적으로 다양한 지원 형식
| 분류 | 지원 형식 |
|---|---|
| 문서 | PDF, Word(.docx), PowerPoint(.pptx), Excel(.xlsx/.xls) |
| 미디어 | 이미지(EXIF + OCR), 오디오(음성 전사) |
| 웹 | HTML, YouTube URL(자막 추출) |
| 텍스트 기반 | CSV, JSON, XML |
| 기타 | ZIP, EPUB, Outlook 메시지 |
② 무료 오픈소스 (Microsoft 개발) Apache 2.0 라이선스. 상업적 사용 가능. Microsoft AutoGen 팀이 직접 관리.
③ CLI와 Python API 모두 지원 터미널 명령어 한 줄로도 실행 가능하고, Python 코드에 import해서 자동화 파이프라인으로도 활용 가능.
④ LLM 연동 기본 내장 GPT-4o 같은 비전 모델을 연결하면 이미지 속 텍스트까지 설명해서 Markdown으로 추출.
⑤ 필요한 형식만 골라 설치 가능 PDF만 쓴다면 PDF 의존성만, Excel만 쓴다면 Excel 의존성만 설치. 전체 설치보다 가볍게 활용 가능.
설치 (Installation) — 터미널에서 한 번만
> ⚠️ Python 3.10 이상 필요. python --version으로 먼저 확인하자.
전체 설치 (추천 — 모든 형식 지원)
pip install 'markitdown[all]'
형식별 선택 설치 (가볍게 쓰고 싶을 때)
# PDF만
pip install 'markitdown[pdf]'
# Word + PowerPoint + Excel
pip install 'markitdown[docx, pptx, xlsx]'
선택 가능한 옵션 전체 목록:
| 옵션 | 설명 |
|---|---|
[pdf] |
PDF 변환 |
[docx] |
Word 문서 |
[pptx] |
PowerPoint |
[xlsx] |
Excel |
[xls] |
구형 Excel |
[outlook] |
Outlook 이메일 |
[audio-transcription] |
오디오 음성 전사 |
[youtube-transcription] |
YouTube 자막 추출 |
[az-doc-intel] |
Azure Document Intelligence 연동 |
[all] |
위 전체 포함 |
사용 (Usage)
CLI — 터미널에서 바로 실행
> 💡 초보자 가이드: 별도 코드 파일 없이 터미널(Windows는 PowerShell 또는 CMD, Mac은 Terminal)에서 명령어만 입력하면 바로 실행된다. VS Code의 내부 터미널(Ctrl + `)을 써도 된다.
# 기본 변환 (결과를 터미널에 출력)
markitdown 파일.pdf
# 결과를 md 파일로 저장
markitdown 파일.pdf -o 결과.md
# 파이프로 연결해서 사용
cat 파일.pdf | markitdown
Python API
> 💡 초보자 가이드: VS Code 또는 Positron을 설치하고, 새 파일을 .ipynb 확장자로 만들면 Jupyter Notebook 환경이 열린다. 셀에 아래 코드를 붙여넣고 Shift + Enter로 실행하면 된다. pip 설치도 VS Code 내부 터미널(Ctrl + `)에서 그대로 실행 가능하다.
기본 사용
from markitdown import MarkItDown
md = MarkItDown()
result = md.convert("파일.pdf")
print(result.text_content) # 변환된 Markdown 출력
여러 파일 일괄 변환
from markitdown import MarkItDown
md = MarkItDown()
for 파일 in ["문서1.pdf", "발표.pptx", "데이터.xlsx"]:
result = md.convert(파일)
with open(파일 + ".md", "w", encoding="utf-8") as f:
f.write(result.text_content)
LLM 연동 — 이미지 속 텍스트까지 추출
이미지 파일을 변환할 때 GPT-4o 같은 비전 모델을 연결하면, 이미지 안의 내용을 AI가 설명해서 Markdown으로 뽑아준다.
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(
llm_client=client,
llm_model="gpt-4o"
)
result = md.convert("이미지.jpg")
print(result.text_content)
Docker — 환경 설치 없이 실행
Python 환경 구성이 어렵다면 Docker로 바로 실행할 수 있다.
docker build -t markitdown:latest .
docker run --rm -i markitdown:latest 결과.md
유의할 점 (Things to Watch Out For)
1. Python 3.10 미만은 동작하지 않는다
설치 전 반드시 버전 확인. python --version으로 체크하자.
2. v0.1.0부터 설치 방식이 바뀌었다
이전 버전(pip install markitdown)으로 설치했다면 의존성이 빠져 있을 수 있다. pip install 'markitdown[all]'로 재설치하자.
3. convert_stream()은 반드시 바이너리로 열어야 한다
open("파일.pdf", "r")이 아니라 open("파일.pdf", "rb")처럼 바이너리 모드로 열어야 한다.
# 잘못된 방법
with open("파일.pdf", "r") as f:
result = md.convert_stream(f) # 오류 발생
# 올바른 방법
with open("파일.pdf", "rb") as f:
result = md.convert_stream(f)
4. LLM 이미지 설명은 API 비용이 발생한다
llm_client를 연결하면 GPT-4o API를 호출하므로 OpenAI 과금이 생긴다. 이미지가 많은 PDF는 비용에 주의하자.
5. OCR은 기본 포함이 아니다 스캔 PDF나 이미지 내 텍스트 추출이 필요하다면 별도 플러그인 설치가 필요하다.
pip install markitdown-ocr
정리 (Summary)
| 항목 | 내용 |
|---|---|
| 개발사 | Microsoft (AutoGen 팀) |
| 라이선스 | Apache 2.0 (상업적 사용 가능) |
| 지원 언어 | Python 3.10+ |
| 지원 형식 | PDF, Word, PPT, Excel, 이미지, 오디오, YouTube, HTML 등 |
| 주요 출력 | Markdown |
| 강점 | 형식 다양성, CLI 지원, LLM 연동, 선택적 설치 |
| 주의 | Python 3.10+, 바이너리 모드 필수, LLM 연동 시 API 비용 |
PDF 하나만 변환하는 게 아니라 여러 형식의 파일을 LLM에 넣어야 하는 상황이라면 MarkItDown이 가장 편한 선택이다. CLI로 바로 쓸 수 있어서 코딩을 몰라도 터미널만 열면 시작할 수 있다.
Hyungrok 