MarkItDown은 웹 스크래퍼와 함께 묶여서 이야기되는 경우가 많지만, 사실 그건 오해야. 이 도구에는 크롤러도 없고, JavaScript 실행 엔진도 없고, URL을 가져와서 쓸데없는 HTML 요소를 걷어내는 기능도 없다. 대신 하는 일은 이미 갖고 있는 바이트, 즉 PDF, Word 문서, 스프레드시트, 슬라이드 덱 같은 파일을 받아 LLM이 읽기 좋은 Markdown으로 바꾸는 것이다.
나는 Microsoft의 MarkItDown을 가지고 단일 Mac에서 실제 문서들을 몇 주 동안 연속으로 테스트했다. 각 표는 실행 전에 미리 만들어 둔 매니페스트와 비교해서 점수를 매겼고, 변환 시간도 전부 측정했다. 결론부터 말하면, 깔끔한 입력에서는 빠르고 충실했지만, 패키징 쪽에는 요청하지도 않은 73MB짜리 머신러닝 런타임이 숨어 있었고, 표 처리에서는 “텍스트는 살아남았는가?”라는 기준은 통과해도 “데이터가 제대로 된 열에 들어갔는가?”에서는 실패하는 경우가 있었다. 이제 숫자와 함께 전체 그림을 보자.
MarkItDown은 정확히 무엇인가
MarkItDown은 Microsoft가 만든 Python 유틸리티로, 파일과 Office 문서를 LLM에 최적화된 Markdown으로 변환한다. PDF, .docx, .xlsx, .pptx, 이미지, HTML 파일, 그리고 몇 가지 다른 형식을 넣으면 Markdown을 돌려준다. 호출 방법은 세 가지다. CLI(markitdown file.pdf -o out.md, 또는 stdin 파이프로 입력), Python API(MarkItDown().convert(...)), 그리고 에이전트 워크플로용 선택적 MCP 서버다.
가장 중요한 포인트는 이 도구가 무엇을 하지 않는가다. README가 그렇게 주장하지도 않고, 테스트로도 확인됐듯이 크롤링, JS 렌더링, 링크 추적, 페이지네이션, readability 스타일의 본문 추출은 하지 않는다. 이건 문서 전체 변환기다. 사용자가 바이트를 가져오면, 이 도구가 그걸 표준화한다. 바로 이 차이가 이 도구가 네 스택에 들어갈지 말지를 결정하니까, 계속 이 부분을 짚어갈 거다.
저장소 자체는 GitHub의 가시성 지표로 보면 꽤 무거운 편이다. 2026년 7월 중순 기준 165,282개 스타와 11,790개 포크를 기록했고, MIT 라이선스이며 최신 릴리스(v0.1.6)는 2026-05-26에 나왔다. 다만 이 스타 수는 Microsoft 조직의 저장소가 LLM 도구 전반의 열기를 타고 올라간 결과이지, 변환 코어의 성숙도를 뜻하는 지표는 아니다. 열린 이슈도 833개나 있고, 그중 몇몇은 설치 전에 꼭 알아야 할 내용이다(아래에서 설명).
HTML to Markdown: 빠르고 충실하지만, 불필요한 요소까지 함께
내 스크래퍼 리뷰 시리즈의 나머지와 똑같이 네 개의 웹 테스트 페이지를 MarkItDown에 넣었다. 이건 이 도구를 스크래퍼로 평가하려는 게 아니라, HTML to Markdown 변환 품질을 보기 위해서였다. 구조가 잘 잡힌 페이지에서는 결과가 꽤 괜찮았다.
네 페이지 모두 기본 설치만으로 변환됐고, 추가 구성요소는 필요 없었다. 본문 콘텐츠도 전부 살아남았다. Wikipedia의 "Web scraping" 문서(226KB)는 헤딩 구조가 그대로 반영돼서 h1 하나, h2 일곱 개, h3 열두 개가 원문 섹션 구조와 맞아떨어졌고, 418개의 링크도 [text](url) 형태로 그대로 보존됐다. Scrape This Site forms 페이지의 26×9 하키 통계 표는 깔끔한 27행 GFM 파이프 테이블(헤더 + 구분선 + 데이터 26행)로 변환됐고, 빈 셀도 그대로 유지됐다. 속도도 문제없었다. 작은 quotes 페이지는 중앙값 48ms, 226KB인 Wikipedia 페이지는 352ms였다.
다만 여기엔 함정이 하나 있다. 이건 버그라기보다 설계 선택에 가깝다. MarkItDown은 불필요한 요소를 제거하지 않는다. <body> 전체를 변환하기 때문에 사이트 공통 UI 요소까지 함께 따라오고, 그 잔여물은 페이지에 쓸데없는 요소가 많을수록 더 커진다.
| 페이지 | 출력 문자 수 | 헤딩(h1/h2/h3) | 링크 수 | 사이트 공통 UI 줄 |
|---|---|---|---|---|
| Books to Scrape | 10,478 | 1 / 0 / 0 | 94 | 0.6% (1/159) |
| Quotes to Scrape | 2,973 | 1 / 1 / 0 | 55 | 1.2% (1/86) |
| ScrapeThisSite forms | 3,385 | 1 / 0 / 0 | 31 | 6.7% (5/75) |
| Wikipedia Web scraping | 60,159 | 1 / 7 / 12 | 418 | 12.4% (42/338) |
공통 UI가 거의 없는 Books 홈페이지에서는 출력 줄의 0.6%만이 공통 UI였다. 반면 Wikipedia에서는 12.4%에 달했다. 338개의 비어 있지 않은 줄 중 42개가 "jump to content", "목차 토글", "22 languages", "retrieved from", 쿠키 및 라이선스 푸터 같은 내용이었다. Wikipedia의 유지보수 배너("이 문서는 추가 인용이 필요합니다")까지도 충실하게 두 열짜리 파이프 테이블로 렌더링되며, 실제 데이터 테이블이 없는 페이지에서 테이블 행이 9개나 생기는 이유가 된다.
이 모든 건 MarkItDown이 잘못하고 있다는 뜻은 아니다. 이 도구는 전체 문서 변환기이지 readability 추출기가 아니다. 충실한 HTML to Markdown 변환과 깔끔한 글 본문 추출은 완전히 다른 작업이다. Trafilatura나 Firecrawl 계열 도구는 본문만 뽑아내는 걸 목표로 하지만, MarkItDown은 페이지 전체를 돌려준다. 내부적으로는 _html_converter.py가 <script>와 <style>를 제거한 뒤 전체 body를 markdownify 라이브러리에 넘기며, 본문 추출을 위한 휴리스틱은 전혀 없다. 기사 본문만 필요하다면 이 도구는 잘못된 계층에 있다.
본업: PDF, DOCX, XLSX, PPTX
MarkItDown이 가장 잘하는 영역은 문서다. 나는 텍스트 레이어가 있는 arXiv 논문, 비트코인 백서, 텍스트가 전혀 없는 이미지 전용 스캔 PDF, 그리고 MarkItDown 자체 테스트 스위트의 DOCX/XLSX/PPTX 파일을 직접 돌려봤다(조용한 콘텐츠 손실을 잡아내기 위해 UUID를 심어 둔 파일들이다).
| 문서 | 입력 | 출력 문자 수 | 프로브 통과 | 중앙값 시간 | 비고 |
|---|---|---|---|---|---|
| arXiv 1706.03762 (텍스트 레이어 PDF) | 2.2 MB | 40,174 | 7/7 | 3.7초(warm) | 제목, "Transformer", "BLEU", "References" 모두 포함 |
| Bitcoin 백서 (9쪽 PDF) | 184 KB | 22,485 | 6/6 | 1.4초 | "Satoshi Nakamoto", "proof-of-work", "Conclusion" 포함 |
| 스캔 PDF (텍스트 레이어 없음) | 89 KB | 0 | 0/4 | 15ms | 빈 출력, 오류 없음, OCR 없음 |
| DOCX (test.docx) | 136 KB | 4,651 | — | 70ms | 헤딩 + GFM 표; 삽입 UUID 유지 |
| 수식이 포함된 DOCX | 15 KB | 240 | — | 101ms | Office Math가 LaTeX로 보존됨 |
| XLSX (test.xlsx) | 12 KB | 808 | — | 57ms | 각 시트 → ## SheetName + GFM 표 |
| PPTX (test.pptx) | 278 KB | 2,047 | — | 52ms | 슬라이드 번호 표식, 표, 차트 → 표 |
텍스트 레이어 PDF에서의 텍스트 회수율은 매우 좋았다. arXiv “Attention Is All You Need” 논문에서는 사전 등록한 프로브 7개 중 7개, Bitcoin 백서에서는 6개 중 6개가 모두 성공했다. 또한 Office 파일은 UUID 시그널 하나도 잃지 않았으니, 유지보수자들이 써 둔 회귀 테스트 파일에서는 조용한 콘텐츠 손실이 없었다. 좁지만 꽤 유용한 장점 하나를 꼽자면, DOCX 경로(mammoth 기반)는 Office Math 수식을 LaTeX로 보존한다는 점이다. equations.docx가 실제 $$...$$ 수식으로 변환된다. 수식이 많은 Word 문서를 LLM에 넣는다면, 이건 아주 구체적이지만 실질적인 장점이다.
이 영역에서 특히 눈에 띄는 결과가 두 가지 있는데, 실제로 사용자에게 가장 문제가 될 가능성이 큰 부분이기도 하다.
사라지는 스캔 PDF
텍스트 레이어가 없는 이미지 전용 PDF를 MarkItDown에 넣으면 빈 문자열이 나온다. 문자 수 0, 예외 없음, 경고 없음. 뽑을 게 없으니 약 15ms 만에 끝난다. MarkItDown의 PDF 경로는 오직 텍스트 추출만 하며(pdfminer와 pdfplumber가 내부적으로 사용됨), 기본 설치에도 pip extra에도 OCR은 없다.
이 점은 배치 처리에서 특히 중요하다. 폴더 안의 PDF 중 일부가 스캔본이면, 그 파일들은 아무 신호 없이 조용히 빈 결과로 떨어진다. 나는 pdfminer의 extract_text를 직접 돌려서 해당 fixture가 깨진 게 아니라는 점을 확인했다. 스트립된 문자 수는 0이었고 텍스트 레이어도 없었다. 즉, 빈 출력은 실제 스캔 파일에 대한 MarkItDown의 실제 동작이다. 이는 오래전부터 열려 있던 OCR fallback 공백(#1268)을 그대로 재현한다. 문서화된 우회 경로는 선택적 Azure Document Intelligence 백엔드나 플러그인인데, 둘 다 기본 설치에는 들어 있지 않다.
PDF는 구조가 아니라 평면 텍스트로 나온다
두 텍스트 레이어 PDF 모두에서 MarkItDown은 Markdown 헤딩 마커를 하나도 만들지 않았다. PDF 자체에는 의미론적 헤딩 태그가 없고, MarkItDown은 글자 크기로 헤딩을 추론하지 않기 때문에 모든 줄이 본문 수준에 놓인다. 텍스트 회수는 훌륭하지만, 구조는 평평하다.
이건 내 결과만 그런 게 아니다. 공개 벤치마크에서도 MarkItDown의 PDF 헤딩 계층 점수는 0.0에 가깝고, 표 충실도는 약 0.27 수준으로, Docling의 TableFormer 기반 0.88보다 훨씬 낮게 나온다(MarkItDown vs Docling vs Marker 비교와 READoc 벤치마크 참고). 내 테스트도 같은 흐름을 재현했다. 이건 증거의 힘이기도 하다. 내 수치가 외부 결과와 맞아떨어지기 때문이다. 같은 벤치마크들이 보여주는 트레이드오프는 MarkItDown이 Docling보다 약 100배 빠르다는 점인데, 레이아웃 모델이 몇 분씩 걸리는 문서에서 내가 측정한 “초 단위” 결과와도 잘 맞는다. 핵심은 이거다. MarkItDown은 PDF의 텍스트를 빠르고 깔끔하게 얻어주지만, PDF의 구조까지는 보존해주지 않는다. 헤딩과 표를 반드시 살려야 한다면 Docling이나 Marker처럼 레이아웃 모델 기반 도구가 맞는 계층이다.
표: 텍스트는 항상 살아남지만, 구조는 가끔 무너진다
표는 “텍스트가 살아남았는가?”와 “실제로 쓸 수 있는 데이터인가?”가 갈리는 영역이다. 그래서 나는 13개 케이스 매트릭스를 만들었다. 각 케이스마다 하나의 <table>을 사용했고, 실행 전에 작성해 둔 매니페스트와 대조해 어떤 형태가 유지되고 어떤 형태가 깨지는지 정확히 추적했다.
한 줄로 요약하면, MarkItDown은 표 콘텐츠를 한 번도 잃지 않았다. 13개 사례 모두에서 사전 등록한 토큰의 100%가 유지됐다. 하지만 구조 충실도는 세 갈래로 나뉘었다. 13개 중 7개는 깔끔한 GFM 그리드로 출력됐다(일반 표, 헤더 colspan, 24열 너비, 헤더 없는 표, 빈 셀, 블록 안의 셀, 그리고 오른쪽에서 왼쪽으로 읽는 아랍어 표). 4개는 Markdown에 병합 셀 개념이 없어서 어수선하게 출력됐다. rowspan, colspan, 그리고 형식이 좋지 않은 소스는 짧은 행을 만들어낸다. 그리고 2개는 완전히 깨졌다.
그 두 가지는 꼭 짚고 넘어갈 만하다. nested table(<td> 안에 <table>)은 인라인으로 평탄화되며, 내부의 파이프와 구분선 행이 부모 셀 안에 그대로 들어가 14개 "열"짜리 쓰레기 행을 만든다. 또 셀 안의 문자 그대로의 |는 이스케이프되지 않는다. 셀 텍스트 a | b는 두 열로, x || y는 세 열로 쪼개진다. 그래서 두 열짜리 표에서 어떤 행은 두 열, 어떤 행은 세 열, 네 열이 되며, 뒤에서 Markdown 파서가 경계를 잘못 읽게 된다. 흥미롭게도 셀 안의 별표와 백틱은 이스케이프되지만, 파이프는 아니다. 근본 원인은 MarkItDown의 HTML 경로가 markdownify의 기본 표 처리 로직을 쓰고, 커스텀 서브클래스가 링크, 이미지, 헤딩만 오버라이드하고 셀은 오버라이드하지 않기 때문이다. 같은 파이프 이스케이프 버그 계열은 CSV 변환기에서도 열린 이슈(#2019)로 남아 있지만, 그 수정은 내가 테스트한 HTML 경로에는 영향을 주지 않는다.
가장 미묘한 문제, 그리고 데이터 엔지니어라면 반드시 봐야 할 결과는 rowspan이다. t03 케이스는 단순히 어수선해지는 수준이 아니라, 데이터를 조용히 잘못 정렬시킨다. rowspan=2 라벨("Fruit")은 한 번만 출력되고, 그 아래 행은 짧은 두 열 행(| Banana | 8 |)이 되어 "Banana"가 Item이 아니라 Group 열 아래로 들어간다. 모든 토큰은 존재한다. 하지만 단순히 "두 번째 열을 읽는" 소비자는 잘못된 값을 얻게 된다. 이런 유형의 버그는 텍스트 생존 여부 테스트는 통과하지만 데이터셋을 조용히 오염시킨다.
이 span 한계는 이미 알려져 있고 추적 중인 설계 제약이다(#1211, #1248). 평평한 GFM 파이프 그리드는 span이나 중첩을 제대로 표현할 수 없기 때문에, 이 변환기는 구조를 포기하는 대신 콘텐츠 완전성을 택한다. 물론 좋은 동작도 있다. 헤더 없는 표는 비어 있는 헤더 행이 자동 생성돼서 데이터가 헤더로 잘못 승격되지 않고, 빈 셀은 그대로 보존되며, <caption>은 표 위의 텍스트 줄로 살아남는다.
설치와 시작 시간: ‘가벼운 유틸리티’라는 말이 숨기는 비용
이번 테스트에서 가장 예상 밖이었던 부분이 바로 여기였고, “가벼운 Python 유틸리티”라는 말이 조용히 과장되기 쉬운 지점이기도 하다.
먼저, pip install 'markitdown[all]'는 하지 않는 게 좋다. Python 3.14에서 이 명령은 조용히 markitdown 0.0.2로 되돌아가는데, 이건 2년 전 릴리스다. 깨끗한 venv에서 직접 재현했다. 버전을 고정하면 이유가 보인다. pip install 'markitdown[all]==0.1.6'는 에러가 나는데, [all] extra가 youtube-transcript-api~=1.0.0를 고정하고 있고, 현재 PyPI에서는 이 범위의 모든 빌드가 Python <3.14로 제한돼 있으며, 3.14와 호환되는 빌드들은 이 핀 범위 밖에 있기 때문이다. 그 결과 resolver가 만족 가능한 의존성이 있는 마지막 릴리스까지 쭉 되돌아간다. 이건 열린 상위 이슈(#2179)와도 맞아떨어진다. 해결책은 단순하다. 버전을 고정하고 extra를 개별로 설치하면 된다: pip install 'markitdown==0.1.6' 후 pip install 'markitdown[pdf,docx,pptx,xlsx,xls]==0.1.6'. 각각은 문제없이 설치되지만, [all] 묶음에만 문제 있는 핀 값이 들어 있다. (이 함정은 Python 버전에 따라 달라진다. Python 3.13 이하에서는 이 제한에 안 걸릴 수 있어 [all]의 해결 결과가 달라질 수 있다.)
둘째, 용량이다. 핵심 설치만으로도 161MB다(빈 venv 13MB + 추가 148MB). 이 중 onnxruntime(73MB)와 numpy(34MB)가 합쳐서 107MB로, 전체 핵심 설치의 66%를 차지하고, 둘 다 단 하나의 하드 의존성인 magika — Google의 ML 파일 형식 감지기 — 때문에 딸려 들어온다. 즉, 텍스트 변환기가 기본 설치 단계에서 이미 73MB짜리 ONNX 추론 런타임을 함께 싣고 있는 셈이다. 문서 extra까지 추가하면 venv는 310MB까지 커진다. 헤드리스 브라우저 스택보다는 훨씬 가볍지만, 진짜로 pip install 한 번으로 끝나는 초소형 유틸리티를 기대했다면 ONNX 런타임이 같이 온다는 점은 알아둘 필요가 있다.
셋째, 그리고 내가 실행한 모든 새로 설치 검사에서 가장 분명하게 드러난 유일한 결과인데, 깨끗한 설치 후에도 import markitdown은 이 머신에서 약 3.35초가 걸린다. 비용은 거의 전부 import 시점에 발생한다. markitdown._markitdown이 전체 변환기 레지스트리를 미리 import하기 때문인데(누적 2.56초, 전체의 76%), 이 과정에서 XLSX 변환기를 통해 pandas(594ms), python-pptx(427ms), magika(354ms), requests(270ms)가 포함되며, 실제로 그 형식을 변환하지 않더라도 전부 로드된다. 장기 실행 서비스라면 이 비용이 한 번만 들기 때문에 큰 문제는 아니다. 하지만 CLI 한 번 실행하거나 서버리스 콜드 스타트를 겪는 경우에는, “가벼운 유틸리티”라는 표현이 전혀 예상시키지 않는 실제 프로세스 비용이 된다. (공정하게 말하면, 이건 단일 프로파일 실행 결과이므로 다회 측정 분포가 아니라 하나의 관측값으로 봐야 한다.)
대규모 처리: 죽지는 않지만, PDF에는 CPU 예산을, 스프레드시트에는 RAM 예산을 잡아야 한다
네 개의 대형 대상 파일을 각각 별도 프로세스로 돌려봤다. 이전 실행의 메모리 영향이 남지 않게 하려는 목적이었다. 어느 것도 크래시하지는 않았다. 다만 비용 구조는 꽤 한쪽으로 치우쳐 있었다.
| 대상 | 입력 | 출력 문자 수 | 중앙값 시간 | 최대 RSS 증가량 |
|---|---|---|---|---|
| NIST SP 800-53r5 (492쪽 PDF) | 5.9 MB | 1,625,365 | 192.5초 | +40 MB |
| XLSX 50,000행 × 8열 | 2.1 MB | 3,722,955 | 62.1초 | +374 MB |
| arXiv 1706.03762 (~15쪽 PDF) | 2.2 MB | 40,174 | 12.6초 | +25 MB |
| XLSX 200행 × 64열 | 46 KB | 120,129 | 2.9초 | +22 MB |
492쪽짜리 NIST PDF는 중앙값 192.5초, 즉 약 3.2분이 걸렸다. 페이지당 0.39초 정도다. 이유는 pdfplumber가 모든 페이지에서 단어 위치 기반 폼 감지를 수행하기 때문이다. 최대 RSS는 +40MB에 머물렀으니 메모리보다 CPU에 더 묶인 셈이다. 같은 arXiv PDF도 독립 프로세스에서는 12.6초가 걸렸는데, 문서 스위트 안에서 warm 상태로 측정한 3.7초의 약 3.4배다. 이 차이는 콜드 프로세스 비용이고, 바이트 크기 자체보다 페이지별 처리 작업이 시간을 좌우한다는 뜻이다. 이 PDF에 대한 하나의 전이 가능한 숫자를 고르라면 격리 실행의 12.6초를 쓰는 게 맞다.
스프레드시트 경로는 병목이 반대로 바뀐다. 2.1MB, 50,000행짜리 XLSX는 최대 RSS가 +374MB까지 치솟았고(출력 문자 수도 370만 자 이상), 변환기가 전체 시트를 메모리에 올린 뒤 거대한 Markdown 문자열 하나를 만들기 때문이다. 따라서 실전 가이드는 단순하다. 큰 PDF는 CPU를 분 단위로 예산 잡고, 큰 스프레드시트는 RAM을 수백 MB 단위로 잡아야 한다. 이 수치는 macOS arm64와 Python 3.14에서 얻은 단일 머신 결과이며, 페이지당/행당 상수는 플랫폼에 따라 달라질 수 있다. 하지만 전반적인 형태, 즉 PDF는 느리고 CPU 집약적이며 XLSX는 메모리를 많이 먹고 크래시는 없다는 점은 그대로 이어진다.
Thunderbit가 들어갈 자리, 그리고 들어가지 않는 자리
이 비교는 쉽게 과장될 수 있어서 선을 분명히 긋고 싶다. MarkItDown과 Thunderbit은 같은 문제가 아니라 인접한 문제를 푸는 도구다.
MarkItDown은 이미 가지고 있는 파일을 변환한다. Thunderbit은 먼저 페이지를 가져온다. Thunderbit의 /distill 엔드포인트는 살아 있는 웹페이지를 깨끗하고 LLM 친화적인 Markdown으로 바꿔 주고, MarkItDown이 다루지 못하는 JS 렌더링, 안티봇, 동적 콘텐츠까지 처리한다. 또한 /extract 엔드포인트는 단순 원문 Markdown이 아니라 스키마에 맞는 구조화된 JSON을 돌려준다. 개발자에게는 이게 하나의 AI 엔진 위에서 API(POST /distill / POST /extract), MCP 서버, CLI(npx @thunderbit/thunderbit-cli)로 제공되며, 100,000명 이상이 쓰는 확장 프로그램을 뒷받침하는 바로 그 엔진이다.
즉, 둘은 딱 한 가지 — “LLM-ready Markdown”을 내보낼 수 있다는 점 — 에서만 겹친다. 하지만 입력 도메인은 다르다. Thunderbit의 distill은 오픈 웹의 URL을 받고, MarkItDown은 로컬 파일을 받는다. 둘은 대체재가 아니고, 나는 그렇게 말하지 않을 거다. 현실적인 스택은 둘을 함께 쓰는 방식이다. 웹은 Thunderbit(또는 Firecrawl 계열 서비스)로 가져오고 크롤링한 뒤, 동시에 갖고 있는 로컬 문서들, 즉 PDF, 프레젠테이션, 스프레드시트는 MarkItDown으로 정규화한다. 하나는 네트워크를 다루고, 다른 하나는 파일 캐비닛을 다룬다.
장점과 단점
장점
- 깔끔한 HTML에서 본문 전체를 완전히 회수(4/4 페이지), 헤딩 구조와 링크도 충실히 보존
- PDF/DOCX 텍스트 회수율이 높고(arXiv 7/7, Bitcoin 6/6), 유지보수자들의 Office fixture에서도 조용한 콘텐츠 손실이 없음
- Office Math 수식을 LaTeX로 보존 — 보기 드문 실질적 강점
- 492쪽 PDF와 5만 행 XLSX까지 어떤 규모에서도 크래시 없음
- 호출이 간단함: CLI,
convert(), stdin 파이프, 선택적 MCP 서버 - MIT 라이선스, Microsoft가 적극 유지보수, 반응이 빠른 이슈 트래커
단점
- 불필요한 요소를 제거하지 않음 — Wikipedia에서 최대 12.4%의 공통 UI 줄; 기사 추출기는 아님
- span, 중첩, 셀 내부 파이프에서 표가 깨짐(13개 중 2개 완전 파손, 4개 어수선), rowspan은 데이터를 조용히 잘못 정렬시킴
- 스캔/이미지 전용 PDF는 OCR도 오류도 없이 빈 출력
- PDF 출력에 헤딩 구조가 전혀 없음(공개 벤치마크와 일치)
- 73MB ONNX 런타임을 포함한 161MB의 핵심 설치 용량, 약 3.35초의 콜드 import
[all]extra가 Python 3.14에서 조용히 2년 전 0.0.2로 되돌아감
누가 써야 하고, 누가 쓰면 안 되는가
여러 형식의 로컬 문서 — Word, Excel, PowerPoint, 텍스트 레이어가 있는 PDF — 를 LLM 파이프라인용 Markdown으로 표준화하고 싶고, 구조 보존보다 완전한 텍스트를 더 중요하게 여긴다면 MarkItDown을 고를 만하다. 배치 작업의 마지막 단계에서 모델에 깨끗한 텍스트를 공급하는 용도라면 빠르고, 충실하고, 무료다.
반대로 아래에 해당한다면 이 도구를 단독으로 쓰지 말고 다른 도구와 함께 쓰거나 아예 건너뛰어야 한다. 웹페이지에서 본문만 필요하다면 readability 또는 Firecrawl 계열 도구를 써야 한다. PDF의 헤딩과 표가 온전히 살아 있어야 한다면 Docling이나 Marker 쪽이 맞다. 입력에 OCR이 필요한 스캔 문서가 포함돼 있다면 Azure 백엔드나 완전히 다른 도구가 필요하다. 그리고 네가 찾던 것이 크롤링하고 가져오는 의미의 스크래퍼라면, 이건 전혀 아니다.
내가 스크래퍼 관점의 루브릭으로 임시 채점했을 때 MarkItDown은 60/100을 받았는데, 이 낮은 점수는 크롤러 시험지로 변환기를 평가한 데 따른 착시다. 이 도구의 본업에서는 텍스트 충실도 점수가 높다. 약한 부분은 구조(PDF 헤딩, 표)와 패키징(용량, import, [all] 함정)이지 텍스트 품질이 아니다. 파일-마크다운 변환기라는 본질대로 평가하면, 이 도구는 생산 환경에 넣기 전에 몇 가지 날카로운 모서리만 알아두면 되는, 꽤 탄탄하고 잘 관리되는 도구다.
자주 묻는 질문
MarkItDown은 웹 스크래퍼인가요?
아니다. 크롤러도 없고, JavaScript 렌더링도 없고, 링크 추적도 없고, 페이지네이션도 없다. 이미 갖고 있는 파일과 문서 — PDF, DOCX, XLSX, PPTX, 이미지, HTML — 를 Markdown으로 바꾸는 도구다. 살아 있는 웹페이지를 가져오고 크롤링해야 한다면 Thunderbit이나 Firecrawl 같은 스크래핑 도구가 필요하고, MarkItDown은 그다음 단계에서 가져온 파일이나 로컬 파일을 깔끔한 Markdown으로 바꾸는 역할이다.
왜 pip install markitdown[all]은 오래된 버전을 설치하나요?
Python 3.14에서 [all] extra는 youtube-transcript-api~=1.0.0를 고정하는데, 그 범위의 모든 빌드는 Python 3.14 미만으로 제한돼 있다. resolver가 그 핀을 만족시킬 수 없어서 조용히 markitdown 0.0.2, 즉 2년 전 릴리스로 되돌아간다. 해결책은 버전을 고정하고 extra를 개별 설치하는 것이다: pip install 'markitdown==0.1.6' 후 'markitdown[pdf,docx,pptx,xlsx,xls]==0.1.6'을 추가한다. 이 문제는 issue #2179로 추적 중이다.
MarkItDown은 스캔 PDF에 OCR을 하나요?
기본 설치에서는 하지 않는다. PDF 경로는 텍스트 추출 전용이어서 텍스트 레이어가 없는 이미지 전용 PDF는 빈 문자열을 돌려준다. 오류도 경고도 없다. OCR이 필요하면 선택적 Azure Document Intelligence 백엔드나 플러그인이 필요하고, 둘 다 기본 제공은 아니다. 이건 오래전부터 알려진 공백이다(issue #1268).
MarkItDown은 표를 얼마나 잘 처리하나요?
콘텐츠 측면에서는 아주 잘한다. 내가 13개 케이스로 테스트했을 때 모든 경우에서 표 콘텐츠의 100%를 유지했다. 구조 측면에서는 모양에 따라 다르다. 단순 표, 넓은 표, 헤더 없는 표, 빈 셀이 있는 표는 깔끔한 GFM 그리드로 나오지만, rowspan과 colspan은 어수선해지고(rowspan은 데이터를 잘못된 열로 조용히 밀어낼 수도 있음), 중첩 표는 쓰레기 같은 행으로 평탄화되며, 셀 내부의 문자 그대로 파이프는 이스케이프되지 않는다. Markdown의 평면 표 형식은 span이나 중첩을 표현할 수 없다.
MarkItDown은 큰 문서도 충분히 빠른가요?
큰 파일에서도 크래시하지는 않지만, 리소스 예산은 형식별로 따로 잡아야 한다. 492쪽 PDF는 페이지별 폼 감지 때문에 약 3.2분(페이지당 약 0.39초)이 걸렸고 CPU 집약적이었다. 5만 행 스프레드시트는 약 1분 만에 끝났지만, 메모리에 큰 Markdown 문자열을 쌓기 때문에 RAM을 +374MB 사용했다. 큰 PDF는 CPU를 분 단위로, 큰 스프레드시트는 RAM을 수백 MB 단위로 준비하는 게 맞다.
웹 데이터 추출을 위해 Thunderbit 체험하기 Get Started Free
