MarkItDown: 한 가지 작업 따라 하기
MarkItDown PDF 패키지를 설치하고 로컬 PDF를 Markdown 파일로 변환하는 과정을 따라가요. 제목·표·숫자를 원본과 대조하고 결과 파일을 확인하는 방법도 정리했어요.
마지막 업데이트
메뉴나 지원 기능이 달라졌다면 아래 자료 확인일과 현재 앱 버전을 함께 봐주세요.

로컬 PDF 문서를 마크다운으로 깔끔하게 바꾸고 싶을 때가 많으시죠. 문서의 제목·목록 같은 구조를 Markdown으로 표현하는 데 초점을 둔 도구인 MarkItDown을 함께 살펴보려고 해요. 이 문서는 공식 문서 기반의 가이드이며 직접 실행한 후기나 측정 결과는 아니에요. F1 파이썬 환경에서 PDF 파일을 손쉽게 마크다운으로 변환하는 과정을 차근차근 정리해 드릴 테니 천천히 따라와 주세요.
이 글은 MarkItDown v0.1.9 공식 릴리스를 다뤄요. 공식 릴리스 기록의 공개일은 2026-10-21(UTC)이고, 자료 확인일은 2026-10-24이에요.
한 가지 완성 목표
이번 글의 목표는 로컬 PDF를 Markdown 파일로 변환한 뒤, 원문과 대조해 빠진 내용을 확인하는 작업이에요. F7 MarkItDown 유틸리티를 활용해 제목·목록·표가 출력에 어떻게 나타나는지 확인하는 방법을 익혀요. 복잡한 배치를 원본처럼 재현하는 고충실도 변환 도구는 아니라는 점도 함께 봐야 해요. D2 이 변환 방식은 LLM이나 텍스트 분석 파이프라인에 문서를 바로 입력해야 하는 개발자나 분석가에게 매우 유용해요. 명령어로 변환을 자동화할 수 있지만, 중요한 표나 수치는 원본과 직접 대조하고 필요하면 고쳐야 해요. 변환 성공과 내용의 정확성은 따로 확인해 주세요. F7
준비물과 지원 버전
이 작업을 수행하려면 파이썬이 설치된 환경이 필수적이에요. MarkItDown은 파이썬 3.10부터 3.14 버전까지 지원하고 있어요. 의존성 충돌을 막기 위해 가상 환경을 만들어 사용하는 것을 권장하고 있어요. 표준 파이썬 설치 환경이라면 터미널에서 가상 환경을 생성하고 활성화한 뒤 필요한 패키지를 설치해 주시면 돼요. 전체 기능과 모든 선택적 의존성을 한 번에 설치하려면 패키지 설치 도구인 pip 명령어를 사용할 수 있어요. F3, F4 예를 들어 macOS·Linux 터미널에서는 아래 순서로 별도 작업 환경을 만들 수 있어요. Windows에서는 이 활성화 명령을 그대로 쓰지 말고 사용 중인 셸의 가상 환경 활성화 방법을 확인해 주세요. D2
python -m venv .venv
source .venv/bin/activate
pip install 'markitdown[pdf]'
.venv는 설치한 Python 패키지를 다른 작업과 분리하는 폴더예요. 원본 PDF나 변환 결과를 저장하는 파일이 아니에요. [pdf]는 PDF 변환에 필요한 선택 의존성을 설치한다는 뜻이고, [all]은 모든 선택 의존성을 설치해요. 이 명령은 공식 문서의 설치 방식을 따른 예시이며 여기서 직접 실행하지 않았어요. D2
단계별 입력과 화면
변환을 시작하기 전 예시 입력과 명령어 구조를 정확히 확인해 보는 것이 좋아요. 이 가이드에서 다루는 구체적인 입력 형태는 명령어 기반 인터페이스를 통해 처리돼요. 예시의 source.pdf는 본인이 읽을 권한이 있는 실제 PDF의 경로로 바꿔 주세요. document.md는 변환 뒤 다시 열어 검사할 출력 파일이에요. F7
예시 입력:
markitdown source.pdf -o document.md
위와 같은 명령어를 터미널에 입력하면 현재 디렉터리에 있는 PDF 파일을 지정된 이름의 마크다운 파일로 변환할 수 있어요. 또한 파이프 라인을 활용해 내용을 전달하는 방식도 지원되고 있으니 필요에 맞춰 선택하면 돼요. 입력 단계에서는 파일 경로가 정확한지 확인해 주세요. 같은 이름의 중요한 출력 파일이 있다면 다른 파일명을 정해 원본과 기존 결과를 보존하는 편이 좋아요. F7
결과 확인과 재오픈
명령어가 정상적으로 실행되면 지정한 출력 경로에 마크다운 파일이 생성돼요. 예상 결과는 제목·목록·표 같은 구조를 Markdown으로 표현한 텍스트예요. 모든 PDF에서 같은 구조나 정확성이 보장되지는 않아요. 아래 블록은 형식을 설명하기 위해 적은 예시이며 실제 변환 출력이 아니에요. D2
예상 결과:
# 문서 제목
- 항목 1
- 항목 2
| 표 헤더 1 | 표 헤더 2 |
|---|---|
| 내용 1 | 내용 2 |
완료 조건을 확인하려면 생성된 document.md 파일을 마크다운 뷰어나 에디터로 다시 열어서 원본 PDF의 표와 목록 구조가 깨지지 않고 잘 들어왔는지 눈으로 직접 대조해 보면 돼요. 파일 생성만으로 비교가 끝나지는 않아요. 원본에서 제목 하나, 목록 하나, 표의 열 이름과 숫자를 골라 document.md와 대조해 주세요. 내용이 누락되거나 열 순서가 달라졌다면 수정·재변환이 필요한 상태로 남겨야 해요. 이는 독자가 적용할 확인 절차이며 여기서 확인한 테스트 결과는 아니에요.
오류 해결과 주의사항
문서를 변환하는 과정에서 예기치 않은 오류가 발생할 수 있어요. MarkItDown은 현재 실행 중인 프로세스의 권한으로 입출력 작업을 수행하므로 접근 권한이 없는 자원에 접근하려고 하면 문제가 생길 수 있어요. 신뢰할 수 없는 환경에서는 항상 입력값을 검증해야 해요. F5 또한 필요한 최소한의 변환 함수만 호출하는 것이 안전해요. 의존성 패키지가 누락된 경우 필요한 선택적 의존성 패키지만 개별적으로 다시 설치해 보는 것도 좋은 해결 방법이에요.
문서 기반 비교와 판단
공식 문서는 MarkItDown을 가벼운 Python 유틸리티로 설명하지만, 여기서 처리 속도를 측정하지는 않았어요. F1 복잡한 문서 구조나 시각적 요소가 많은 경우에는 다른 대안을 고려할 수도 있어요. 예를 들어 고급 PDF 이해 기능이나 생성형 AI 생태계 연동을 지원하는 Docling과 문서 기반으로 비교해 볼 수 있어요. F6 결과물 측면에서는 구조 유지력에 차이가 있을 수 있고, 시간이나 호환성 면에서도 각 도구의 특성이 달라요. 시간 차이는 같은 입력으로 직접 실행하기 전에는 판단하지 않아요. 자동화 방식은 MarkItDown의 CLI·Python 호출과 Docling의 공개된 통합 방식을 비교하고, 결과 정확도는 같은 파일의 누락·표 구조·재오픈 결과까지 확인한 뒤 평가해 주세요. D2, D3
공통 예시 입력이에요. 독자가 준비할 입력 조건이며 직접 실행한 기록이 아니에요.
Input file: source.pdf (a local PDF you have permission to process)
Check one heading, one list and one table against the original.
BumbleV가 만든 자료 안내 그림이며 실제 앱 화면이나 실행 결과가 아니에요. 그림의 근거가 된 공식 발표 · CC BY 4.0 · 2026-10-24

참고 자료
- https://github.com/microsoft/markitdown/releases/tag/v0.1.9
- https://raw.githubusercontent.com/microsoft/markitdown/21d9c1d01ecc12538dab19811fd247ef2f96ef60/README.md
- https://raw.githubusercontent.com/docling-project/docling/53c11a20a5dd6ac0d85fe88cc257ca3b4b3a72d4/README.md
- https://api.github.com/repos/microsoft/markitdown