MarkItDown — 설치·사용 가이드 (공식 문서 한글 정리)

11. 한눈에 보기

▸ 무엇인가요
MarkItDown(마크잇다운)은 여러 종류의 파일을 마크다운(Markdown, 제목·목록·표를 간단한 기호로 적는 글 형식)으로 바꿔 주는 가벼운 파이썬(Python) 도구입니다. 원문은 LLM(대형 언어 모델, ChatGPT 같은 AI)과 텍스트 분석 작업에 쓰기 위한 용도라고 설명합니다.
▸ 만든 곳
GitHub 저장소 microsoft/markitdown. LICENSE 파일의 저작권 표기는 Copyright (c) Microsoft Corporation. 입니다.
▸ 형태
파이썬 패키지이자 명령행(터미널에 글자로 명령을 치는 방식) 도구입니다. PyPI(파이썬 패키지 저장소) 이름은 markitdown, 확인 시점 버전 0.1.8, 개발 단계 분류 4 - Beta 입니다.
▸ 라이선스
MIT License (저장소 LICENSE 파일 기준).
▸ 비용
원문 비교표에서 기본 변환기의 비용은 Local compute only(내 컴퓨터 자원만 사용)입니다. Azure 연동 두 가지는 Billable Azure API calls(요금이 청구되는 Azure API 호출)입니다.
▸ 어디서 돌아가나요
파이썬 3.10~3.14 가 있는 컴퓨터, 또는 Docker(도커, 프로그램을 컨테이너라는 상자에 담아 돌리는 도구). 특정 운영체제 제한은 원문에서 확인되지 않았습니다.

22. 이런 분께 맞아요 / 이럴 땐 맞지 않아요

▸ 이런 분께 맞아요
· PDF·워드·엑셀·파워포인트 문서를 AI(LLM)에 넣기 좋은 텍스트로 바꾸려는 분
· 제목·목록·표·링크 같은 문서 구조를 살린 채 텍스트로 뽑으려는 분 (원문: 중요한 문서 구조 보존에 초점)
· 파이썬 코드나 터미널 명령으로 파일을 처리하려는 분
▸ 이럴 땐 맞지 않아요
· 사람이 읽을 고품질 변환이 필요할 때: 원문은 출력이 텍스트 분석 도구용이며 이 용도에는 최선이 아닐 수 있다고 적습니다.
· 클릭으로 쓰는 앱을 원할 때: 원문은 이 저장소가 다른 시스템에 넣어 쓰는 파이썬 라이브러리를 제공하며, 웹 화면·데스크톱·모바일 앱과 웹 서버·호스팅 변환 서비스는 범위 밖이라고 밝힙니다.
· 동영상 변환이 필요할 때: 기본 변환기는 동영상을 지원하지 않고 음성은 기본 받아쓰기만 된다고 원문은 적습니다. 동영상은 유료 Azure Content Understanding 연동만 가능하다고 적혀 있습니다.

33. 시작 전에 준비할 것

▸ 운영체제
원문에 특정 운영체제 요구 사항은 확인되지 않았습니다.
▸ 필요 프로그램
· Python 3.10 부터 3.14 까지 (원문: MarkItDown requires Python 3.10 through 3.14.)
· pip(파이썬 패키지 설치 도구), 또는 uv, 또는 Anaconda(conda)
· 소스 설치는 git, 컨테이너 실행은 Docker
▸ 가상환경(프로젝트마다 따로 쓰는 파이썬 공간) 권장
원문은 의존성(함께 깔리는 다른 패키지) 충돌을 피하려고 가상환경을 권합니다.
1) 기본 파이썬
python -m venv .venv
source .venv/bin/activate
2) uv
uv venv --python=3.12 .venv
source .venv/bin/activate
원문 주석: 이 가상환경에서는 pip install 이 아니라 uv pip install 을 쓰라고 합니다.
3) Anaconda
conda create -n markitdown python=3.12
conda activate markitdown
윈도우용 활성화 명령은 원문에서 확인되지 않았습니다.
▸ 사양(CPU·메모리 등)
원문에서 확인되지 않았습니다.
▸ 계정·API 키
기본 변환에 계정·API 키가 필요하다는 내용은 원문에서 확인되지 않았습니다. 이미지 설명·OCR 플러그인은 OpenAI 호환 클라이언트(llm_client)와 모델(llm_model), Azure 연동은 각 엔드포인트(<document_intelligence_endpoint>, <content_understanding_endpoint>)가 필요합니다.

44. 설치 방법

▸ 방법 1 — PyPI 에서 pip 로 설치 (원문 기본 안내)
모든 선택 기능(선택 의존성)을 함께 설치합니다.
pip install 'markitdown[all]'
▸ 방법 2 — 필요한 형식만 골라 설치
예: PDF·DOCX·PPTX 만 쓸 때
pip install 'markitdown[pdf, docx, pptx]'
원문에 적힌 선택 항목
· [all] 전부 · [pptx] 파워포인트 · [docx] 워드 · [xlsx] 엑셀 · [xls] 예전 엑셀 · [pdf] PDF · [outlook] 아웃룩 메시지
· [az-doc-intel] Azure Document Intelligence · [az-content-understanding] Azure Content Understanding
· [audio-transcription] wav·mp3 음성 받아쓰기 · [youtube-transcription] 유튜브 영상 받아쓰기 가져오기
▸ 방법 3 — 소스 코드에서 설치
git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'
▸ uv 를 쓰는 경우
uv 로 만든 가상환경에서는 pip install 대신 uv pip install 을 쓰라고 원문은 안내합니다.
▸ 방법 4 — Docker
docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md
원문에는 이 두 줄만 있고, build 를 어느 폴더에서 실행하는지는 원문에서 확인되지 않았습니다.

55. 처음 실행해 보기

path-to-file.pdf, test.xlsx 는 원문의 예시 이름입니다. 내 파일 경로로 바꾸세요.
1) 결과를 document.md 파일로 저장 (> 는 출력을 파일로 보내는 기호)
markitdown path-to-file.pdf > document.md
2) -o 옵션으로 출력 파일 지정
markitdown path-to-file.pdf -o document.md
3) 파이프(앞 명령의 결과를 다음 명령에 넘기는 방식)로 넣기
cat path-to-file.pdf | markitdown
4) 파이썬 코드로 쓰기 (원문 기본 예시)
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.markdown)
원문 주석대로 enable_plugins 를 True 로 바꾸면 플러그인이 켜집니다.
5) 보안 원칙대로 쓰기
convert() 는 로컬 파일·원격 주소(URI)·바이트 스트림을 모두 받는 넓은 함수입니다. 내 컴퓨터 파일만 읽는다면 convert_local() 을 쓰라고 원문은 권합니다.

66. 알아 둘 기능

▸ 지원하는 변환 형식 (원문 목록)
· PDF, 파워포인트(PowerPoint), 워드(Word), 엑셀(Excel)
· 이미지: EXIF 메타데이터(사진 촬영 정보)와 OCR(그림 속 글자 읽기)
· 오디오: EXIF 메타데이터와 음성 받아쓰기
· HTML
· 텍스트 기반 형식: CSV, JSON, XML
· ZIP 파일: 안에 든 파일을 하나씩 처리
· 유튜브 주소(YouTube URLs), EPub(전자책)
· 원문 표현 그대로: ... and more!
▸ 왜 마크다운인가 (원문 설명)
일반 텍스트에 가까우면서 문서 구조를 나타낼 수 있고, 주요 LLM 이 잘 이해하며, 토큰(AI 가 글을 세는 단위) 효율도 높다고 설명합니다.
▸ 플러그인(추가 기능 꾸러미)
외부(3rd-party) 플러그인을 지원하며 기본값은 꺼짐입니다.
markitdown --list-plugins
markitdown --use-plugins path-to-file.pdf
첫 줄은 설치된 플러그인 보기, 둘째 줄은 플러그인을 켜고 변환하기입니다. 플러그인은 GitHub 에서 #markitdown-plugin 해시태그로 찾고, 직접 만들려면 packages/markitdown-sample-plugin 을 보라고 안내합니다.
▸ markitdown-ocr 플러그인
PDF·DOCX·PPTX·XLSX 안의 그림에서 LLM 비전(그림을 읽는 AI)으로 글자를 뽑습니다. 새 머신러닝 라이브러리나 바이너리 의존성은 필요 없다고 원문은 설명합니다.
pip install markitdown-ocr
pip install openai # or any OpenAI-compatible client
markitdown document.pdf --use-plugins --llm-client openai --llm-model gpt-4o
▸ LLM 으로 이미지 설명 넣기
현재 pptx 와 이미지 파일에만 해당한다고 원문은 적습니다.
client = OpenAI(max_retries=5)
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
▸ Azure Document Intelligence 연동 (요금 청구)
markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"
▸ Azure Content Understanding 연동 (요금 청구)
문서·이미지·음성·동영상을 클라우드에서 분석하고, 뽑은 항목을 YAML front matter(문서 맨 위 정보 블록)로 넣는다고 원문은 설명합니다.
pip install 'markitdown[az-content-understanding]'
markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"

77. 막힐 때 / 주의할 점

▸ 가장 중요한 보안 주의 (원문 IMPORTANT)
MarkItDown 은 현재 실행 중인 프로세스(프로그램)의 권한으로 입출력(I/O)을 합니다. open() 이나 requests.get() 처럼, 그 프로세스가 접근할 수 있는 자원이면 접근합니다.
· 믿을 수 없는 입력을 바로 넘기지 마세요. 서버·호스팅 앱처럼 남이 입력을 정할 수 있으면 호출 전에 검증하고 제한해야 합니다.
· 원문이 든 제한 예: 파일 경로 제한, URI 방식과 네트워크 목적지 제한, 사설·루프백(내 컴퓨터 자신)·링크 로컬·메타데이터 서비스 주소 차단.
· 필요한 변환 함수만 쓰세요: 로컬 파일만이면 convert_local(), 내려받기를 직접 통제하려면 requests.get() 결과를 convert_response() 에, 가장 엄격하게는 직접 연 스트림을 convert_stream() 에 넘기라고 안내합니다.
▸ 변환 품질의 한계
출력은 텍스트 분석 도구용이며, 사람이 볼 고품질 변환에는 최선이 아닐 수 있다고 원문은 적습니다.
▸ 비용이 생길 수 있는 경우
Azure Content Understanding 으로 가는 형식은 convert() 한 번마다 요금이 청구되는 Azure API 호출이라고 원문은 경고합니다. cu_file_types 로 보낼 형식을 제한할 수 있습니다. OpenAI 등 LLM 연동 요금은 MarkItDown 원문에서 확인되지 않았습니다.
▸ OCR 이 안 될 때
llm_client 를 넘기지 않으면 플러그인은 로드되지만 OCR 은 알림 없이 건너뛰고 기본 변환기를 씁니다. 플러그인이 안 보이면 markitdown --list-plugins 결과에 ocr 이 있는지 확인하라고 합니다. API 오류는 경고만 남기고 변환을 계속하므로 API 키·사용 한도·모델의 이미지 입력 지원 여부를 확인하라고 안내합니다.
▸ 알려진 문제 목록
원문 README 에 별도의 알려진 문제 목록은 확인되지 않았습니다. 문제 확인은 GitHub 저장소의 Issues 에서 합니다.

88. 라이선스와 비용

▸ 라이선스
저장소 LICENSE 파일: MIT License, Copyright (c) Microsoft Corporation.
▸ 원문 조건 요약
MIT 라이선스 원문은 누구에게나 무료로 소프트웨어를 사용·복사·수정·병합·게시·배포·서브라이선스·판매할 권리를 준다고 적습니다. 조건은 저작권 표시와 이 허가 문구를 소프트웨어의 모든 복사본 또는 상당 부분에 포함하는 것입니다. 소프트웨어는 어떤 보증도 없이 "있는 그대로(AS IS)" 제공된다고 적혀 있습니다.
▸ markitdown-ocr 플러그인
플러그인 문서에 License 는 MIT 로 표기되어 있습니다.
▸ 상표
Microsoft 상표·로고 사용은 Microsoft 상표·브랜드 지침을 따라야 하고, 수정판에서 혼동을 주거나 Microsoft 후원을 암시해서는 안 된다고 원문은 적습니다.
▸ 유료판 여부
MarkItDown 자체의 유료판은 원문에서 확인되지 않았습니다. 기본 변환기는 내 컴퓨터 자원만 쓰고, Azure 연동 기능은 요금이 청구되는 Azure API 호출입니다.

99. 면책 및 원문 확인

이 문서는 원저자의 공식 사이트와 깃허브 문서를 한국어로 옮겨 정리한 안내입니다. 가고파는 이 소프트웨어를 개발·배포·보증하지 않으며, 설치·사용으로 생기는 결과(데이터 손실, 보안 문제, 비용, 라이선스 위반 등)에 책임지지 않습니다. 번역·요약 과정의 오류가 있을 수 있고 원문은 수시로 바뀌므로, 설치 전에 반드시 아래 원문(공식 사이트·깃허브)에서 최신 내용을 확인하세요. 제휴 링크·광고가 없습니다.
추가 안내: MarkItDown은 Microsoft가 GitHub에 공개한 오픈소스이며, 이 문서는 Microsoft의 후원이나 보증을 뜻하지 않습니다. Azure·OpenAI 같은 외부 서비스 연동을 켜면 해당 서비스 요금이 생길 수 있습니다. 회사·고객 문서를 변환하기 전에 원문의 보안 주의(현재 프로세스 권한으로 입출력 수행)를 먼저 읽으세요.

원문 주소(복사해서 브라우저 주소창에 붙여넣기):
· GitHub 저장소 (공식 문서 README): https://github.com/microsoft/markitdown
· PyPI 패키지 페이지: https://pypi.org/project/markitdown/
· 보안 주의 (Security Considerations): https://github.com/microsoft/markitdown#security-considerations

이 자료를 보는 방법

이 안내는 인스타그램 카드·릴스에서 다 담지 못한 내용을 담은 무료 자료입니다. 로그인이나 이메일 확인 없이 바로 읽을 수 있고, 링크는 새 창에서 열립니다.

가고파 생활 가이드 시리즈

이 자료는 가고파(Natas Market)가 생활 주제별로 만들어 두는 무료 DM 자료 중 하나입니다. 인스타그램·스레드 카드뉴스에서 줄인 설명을 여기서 자세히 풀어 씁니다.

각 자료는 카드뉴스 1편과 한 세트입니다. 카드에서 “댓글에 ○○ 남겨주세요”로 안내한 경우, 그 키워드를 남기면 이 자료 링크를 받습니다.

자주 묻는 질문