MarkItDown

1. MarkItDown là gì?

MarkItDown là công cụ miễn phí của Microsoft, dùng để đổi các loại file (PDF, Word, Excel, PowerPoint, ảnh, âm thanh, trang web…) thành văn bản Markdown. Markdown là kiểu văn bản thuần, chỉ dùng vài ký hiệu đơn giản để đánh dấu tiêu đề, danh sách, bảng. Các AI như ChatGPT, Claude, Gemini đọc loại văn bản này rất tốt, nên MarkItDown thường được dùng để "dọn" tài liệu trước khi dán cho AI.

Nói thẳng: đây là công cụ dòng lệnh viết bằng Python, không có cửa sổ hay nút bấm. Tuy vậy, cách dùng cơ bản chỉ là một dòng lệnh, nên người không rành kỹ thuật vẫn làm theo được. Dự án cũng nói rõ kết quả là để máy đọc; nếu bạn cần một bản chuyển đổi đẹp, giữ nguyên bố cục để người đọc, đây chưa chắc là lựa chọn tốt nhất.

Công cụ dùng giấy phép MIT, miễn phí hoàn toàn khi chạy trên máy bạn. Chỉ các tính năng tùy chọn gọi dịch vụ đám mây (Azure, hoặc mô hình AI để mô tả ảnh) mới tính tiền theo nhà cung cấp.

Hợp với bạn nếu:

• Bạn hay phải đưa file PDF, Word, Excel, PowerPoint cho AI đọc và muốn nội dung gọn, ít lỗi.
• Bạn có nhiều tài liệu cần rút chữ ra hàng loạt.
• Bạn không muốn tải tài liệu của mình lên các trang chuyển đổi trực tuyến.

Chưa hợp nếu:

• Bạn cần bản chuyển đổi giữ nguyên hình thức, phông chữ, bố cục.
• Bạn chỉ dùng điện thoại.
• Bạn cần đọc chữ trong ảnh quét mà không muốn dùng thêm dịch vụ AI (tính năng này cần plugin và một mô hình AI).

2. Cần chuẩn bị gì?

• Máy tính Windows, macOS hoặc Linux. Không cần card đồ họa.
• Python từ 3.10 đến 3.14: ngôn ngữ lập trình mà MarkItDown chạy trên đó. Tải tại https://www.python.org/downloads/ . Trên Windows, khi cài nhớ tích ô "Add python.exe to PATH".
• Mạng để tải công cụ lúc cài. Khi chuyển đổi file có sẵn trên máy bằng bộ chuyển đổi mặc định thì mọi việc diễn ra ngay trên máy.
• Không cần tài khoản hay khóa API cho cách dùng cơ bản.

Những thứ chỉ cần khi dùng tính năng nâng cao:

Tính năng	Cần thêm	Có mất tiền không
Mô tả ảnh, đọc chữ trong ảnh (OCR)	Khóa API của một dịch vụ AI tương thích OpenAI	Có, theo bảng giá của nhà cung cấp
Azure Document Intelligence	Tài khoản Azure và một địa chỉ endpoint	Có, tính theo lượt gọi
Azure Content Understanding	Tài khoản Azure và một địa chỉ endpoint	Có, mỗi lần chuyển đổi là một lượt gọi tính tiền
Chạy bằng Docker	Docker Desktop, tải tại https://www.docker.com/products/docker-desktop/	Không

3. Cài đặt từng bước

Bước 1: Kiểm tra Python

python --version

Đúng là khi bạn thấy Python 3.10 đến Python 3.14. Trên macOS và Linux, nếu lệnh báo lỗi thì thử python3 --version.

Bước 2: Tạo môi trường riêng (nên làm)

Môi trường ảo (virtual environment) là một thư mục riêng chứa các thư viện của MarkItDown, để không đụng tới phần mềm Python khác trên máy. Dự án khuyên nên dùng.

Windows:

python -m venv .venv
.venv\Scripts\activate

macOS và Linux:

python -m venv .venv
source .venv/bin/activate

Đúng là khi đầu dòng lệnh xuất hiện chữ (.venv). Mỗi lần mở cửa sổ dòng lệnh mới, bạn cần chạy lại lệnh thứ hai (lệnh activate) trước khi dùng MarkItDown.

Bước 3: Cài MarkItDown

Windows:

pip install "markitdown[all]"

macOS và Linux:

pip install 'markitdown[all]'

Phần [all] nghĩa là cài đủ bộ đọc cho mọi định dạng. Đúng là khi dòng cuối có chữ Successfully installed.

Bước 4: Kiểm tra

markitdown --list-plugins

Nếu lệnh chạy và in ra thông tin về plugin (có thể là danh sách trống) thay vì báo "command not found", MarkItDown đã sẵn sàng.

Cách khác: chỉ cài những định dạng bạn cần

Nếu muốn cài gọn, thay [all] bằng danh sách định dạng. Ví dụ chỉ PDF, Word và PowerPoint:

pip install "markitdown[pdf, docx, pptx]"

Các nhóm có sẵn: pptx, docx, xlsx, xls, pdf, outlook, az-doc-intel, az-content-understanding, audio-transcription, youtube-transcription.

Cách khác: chạy bằng Docker

Dành cho người đã quen Docker (phần mềm chạy ứng dụng trong "hộp" kín). Bạn cần tải mã nguồn của repo về, rồi chạy trong thư mục đó:

docker build -t markitdown:latest .

Sau đó chuyển đổi một file (lệnh viết cho macOS và Linux):

docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

4. Dùng lần đầu

Bước 1: Chuyển đổi một file PDF

Đặt một file PDF, ví dụ baocao.pdf, vào thư mục bạn đang đứng, rồi gõ:

markitdown baocao.pdf -o baocao.md

Tùy chọn -o đặt tên file kết quả. Lệnh chạy xong mà không in lỗi là thành công.

Bước 2: Mở kết quả

Trong thư mục xuất hiện file baocao.md. Mở bằng Notepad hoặc bất kỳ trình soạn thảo nào. Bạn sẽ thấy nội dung tài liệu ở dạng chữ, tiêu đề bắt đầu bằng dấu #, bảng được kẻ bằng dấu |. Chép toàn bộ rồi dán cho AI.

Bước 3: Thử với loại file khác

Cùng một lệnh dùng được cho Word, Excel, PowerPoint:

markitdown bangtinh.xlsx -o bangtinh.md

Ngoài PDF và bộ Office, MarkItDown còn nhận ảnh, âm thanh, HTML, CSV, JSON, XML, file ZIP (nó duyệt từng file bên trong), EPUB và đường dẫn YouTube.

Lưu ý: Tài liệu chính thức còn có cách viết markitdown file.pdf > document.md. Trên Windows, hãy ưu tiên dùng -o như trên để file kết quả không bị lỗi bảng mã.

Dành cho người viết code Python

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False)
result = md.convert("test.xlsx")
print(result.markdown)

Tùy chọn: đọc chữ nằm trong ảnh (OCR)

Plugin markitdown-ocr giúp lấy chữ từ ảnh nhúng trong PDF, Word, PowerPoint, Excel bằng một mô hình AI biết nhìn ảnh. Cài đặt:

pip install markitdown-ocr
pip install openai

Plugin này chỉ hoạt động khi bạn viết code Python và truyền vào llm_client cùng llm_model. Cách viết cụ thể xem tại https://github.com/microsoft/markitdown/tree/main/packages/markitdown-ocr

5. Lỗi thường gặp và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
markitdown báo "is not recognized" hoặc "command not found"	Chưa kích hoạt môi trường ảo, hoặc cài chưa xong.	Chạy lại lệnh activate ở Bước 2 rồi thử lại. Nếu vẫn lỗi, chạy lại lệnh cài ở Bước 3.
Lệnh cài báo lỗi về phiên bản Python	MarkItDown chỉ hỗ trợ Python 3.10 đến 3.14.	Kiểm tra bằng python --version và cài bản Python nằm trong khoảng đó.
Chuyển file PDF/Word báo thiếu thư viện	Bạn cài bản gọn, thiếu nhóm định dạng tương ứng.	Cài lại với nhóm cần thiết, ví dụ pip install "markitdown[pdf]", hoặc dùng [all].
Trên macOS/Linux, lệnh cài báo no matches found: markitdown[all]	Thiếu dấu nháy quanh tên gói, nên shell hiểu nhầm dấu ngoặc vuông.	Gõ đúng pip install 'markitdown[all]' có dấu nháy.
Đã cài plugin nhưng không thấy tác dụng	Plugin mặc định bị tắt.	Thêm --use-plugins vào lệnh, hoặc đặt enable_plugins=True trong code Python.
Đã cài markitdown-ocr nhưng chữ trong ảnh vẫn không được đọc	Không truyền llm_client; plugin vẫn nạp nhưng âm thầm bỏ qua OCR.	Truyền đủ llm_client và llm_model khi tạo MarkItDown(...).
Dùng uv tạo môi trường nhưng gói không vào đúng chỗ	Trong môi trường do uv tạo phải dùng uv pip install.	Thay pip install bằng uv pip install.
FileConversionException	Không bộ chuyển đổi nào xử lý được file. Với ảnh, lỗi này chỉ xuất hiện sau khi dịch vụ AI thất bại và các bộ chuyển đổi khác cũng không đọc được.	Kiểm tra file có hỏng không. Nếu đang dùng mô tả ảnh, tăng max_retries của OpenAI client (mặc định là 2).

6. Gỡ cài đặt / cập nhật

Cập nhật (kích hoạt môi trường ảo trước):

pip install -U "markitdown[all]"

Trên macOS và Linux, dùng dấu nháy đơn thay cho nháy kép. Bản mới nhất lúc viết bài là 0.1.8, phát hành ngày 21/9/2026.

Gỡ:

pip uninstall markitdown

Nếu bạn đã tạo môi trường ảo ở Bước 2, cách gỡ sạch nhất là xóa hẳn thư mục .venv: mọi thứ MarkItDown cài thêm đều nằm trong đó. Các file .md bạn đã tạo không bị ảnh hưởng.

7. Câu hỏi hay gặp

MarkItDown có mất tiền không? Không. Công cụ và các bộ chuyển đổi mặc định chạy trên máy bạn, miễn phí. Chỉ khi bạn bật Azure Document Intelligence, Azure Content Understanding hoặc dùng mô hình AI để mô tả ảnh thì mới phát sinh phí từ các dịch vụ đó.

Tài liệu của tôi có bị gửi đi đâu không? Theo bảng so sánh của dự án, các bộ chuyển đổi mặc định làm việc ngoại tuyến, chỉ dùng sức máy của bạn. File chỉ rời máy khi bạn chủ động bật dịch vụ đám mây hoặc truyền vào một mô hình AI. Riêng đường dẫn YouTube và địa chỉ web thì dĩ nhiên cần mạng để lấy nội dung.

Có cần mạng không? Cần lúc cài. Sau đó, chuyển đổi file trên máy không cần mạng.

File PDF là ảnh quét thì sao? Bộ chuyển đổi mặc định rút chữ có sẵn trong file. Với ảnh quét, bạn cần plugin markitdown-ocr kèm một mô hình AI, hoặc dịch vụ Azure.

Có bản ứng dụng có giao diện không? Dự án này chỉ cung cấp thư viện Python và công cụ dòng lệnh. Nhóm phát triển nói rõ họ không nhận thêm ứng dụng web hay ứng dụng máy tính vào repo; nếu có, đó là sản phẩm riêng của bên khác.