MarkItDown
microsoft/markitdown
Converte arquivos para Markdown preservando estrutura, otimizado para LLMs
Ver no GitHubUtilitário Python leve para converter diversos formatos de arquivo (PDF, Word, Excel, PowerPoint, imagens, áudio, HTML, etc.) em Markdown. Preserva estrutura importante do documento (títulos, listas, tabelas, links) mantendo a saída otimizada para consumo por LLMs e pipelines de análise textual.
Instalação
npx convez-ai microsoft/markitdown1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Preparar documentos para análise com modelos de linguagem
- Extrair conteúdo estruturado de PDFs, Word, Excel e PowerPoint
- Processar lotes de arquivos em pipelines de dados e IA
- Integrar OCR e transcrição de áudio em workflows automatizados
Veredito

MarkItDown é uma solução prática e versátil para converter documentos em Markdown com foco real em LLMs. Ideal para quem precisa integrar extração de documentos em pipelines de IA, mas exige atenção com segurança em ambientes com inputs não confiáveis.
README em português
MarkItDown
[!IMPORTANT] MarkItDown realiza I/O com as permissões do processo atual. Assim como
open()ourequests.get(), ele acessa recursos aos quais o próprio processo tem acesso. Limpe suas entradas em ambientes não confiáveis e chame a função mais restritaconvert_*necessária para seu caso de uso (por exemplo,convert_stream()ouconvert_local()). Consulte a seção Security Considerations da documentação para obter mais informações.
MarkItDown é uma ferramenta leve em Python para converter diversos arquivos em Markdown para uso com LLMs e pipelines relacionados de análise de texto. Para esse fim, ela é mais comparável ao textract, mas com foco na preservação da estrutura e do conteúdo importantes dos documentos como Markdown (incluindo: títulos, listas, tabelas, links, etc.). Embora a saída seja frequentemente razoavelmente apresentável e amigável para humanos, ela é destinada a ser consumida por ferramentas de análise de texto — e pode não ser a melhor opção para conversões de alta fidelidade destinadas ao consumo humano.
MarkItDown atualmente suporta a conversão de:
- PowerPoint
- Word
- Excel
- Imagens (metadados EXIF e OCR)
- Áudio (metadados EXIF e transcrição da fala)
- HTML
- Formatos baseados em texto (CSV, JSON, XML)
- Arquivos ZIP (itera sobre o conteúdo)
- URLs do Youtube
- EPubs
- ... e mais!
Por que Markdown?
Markdown é extremamente próximo de texto puro, com marcação ou formatação mínima, mas ainda fornece uma maneira de representar a estrutura importante dos documentos. LLMs principais, como GPT-4o da OpenAI, nativamente "falam" Markdown e frequentemente incorporam Markdown em suas respostas sem solicitação explícita. Isso sugere que eles foram treinados com vastas quantidades de texto formatado em Markdown e o entendem bem. Como benefício adicional, as convenções do Markdown também são altamente eficientes em tokens.
Pré-requisitos
MarkItDown requer Python 3.10 ou superior. Recomenda-se usar um ambiente virtual para evitar conflitos de dependências.
Com a instalação padrão do Python, você pode criar e ativar um ambiente virtual usando os seguintes comandos:
python -m venv .venv
source .venv/bin/activate
Se estiver usando uv, você pode criar um ambiente virtual com:
uv venv --python=3.12 .venv
source .venv/bin/activate
# NOTE: Be sure to use 'uv pip install' rather than just 'pip install' to install packages in this virtual environment
Se você está usando Anaconda, você pode criar um ambiente virtual com:
conda create -n markitdown python=3.12
conda activate markitdown
Instalação
Para instalar o MarkItDown, use pip: pip install 'markitdown[all]'. Alternativamente, você pode instalá-lo a partir do código fonte:
git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'
Uso
Linha de Comando
markitdown path-to-file.pdf > document.md
Ou use -o para especificar o arquivo de saída:
markitdown path-to-file.pdf -o document.md
Você também pode encaminhar conteúdo por pipe (stdin):
cat path-to-file.pdf | markitdown
Dependências Opcionais
MarkItDown possui dependências opcionais para ativar vários formatos de arquivo. Mais cedo neste documento, instalamos todas as dependências opcionais com a opção [all]. No entanto, você também pode instalá-las individualmente para mais controle. Por exemplo:
pip install 'markitdown[pdf, docx, pptx]'
instalará apenas as dependências para arquivos PDF, DOCX e PPTX.
No momento, estão disponíveis as seguintes dependências opcionais:
[all]Instala todas as dependências opcionais[pptx]Instala dependências para arquivos do PowerPoint[docx]Instala dependências para arquivos do Word[xlsx]Instala dependências para arquivos do Excel[xls]Instala dependências para versões antigas de arquivos do Excel[pdf]Instala dependências para arquivos PDF[outlook]Instala dependências para mensagens do Outlook[az-doc-intel]Instala dependências para Azure Document Intelligence[az-content-understanding]Instala dependências para Azure Content Understanding[audio-transcription]Instala dependências para transcrição de áudio de arquivos wav e mp3[youtube-transcription]Instala dependências para obtenção da transcrição de vídeos do Youtube
Plugins
MarkItDown também suporta plugins de terceiros. Os plugins estão desativados por padrão. Para listar os plugins instalados:
markitdown --list-plugins
Para ativar plugins, use:
markitdown --use-plugins path-to-file.pdf
Para encontrar plugins disponíveis, pesquise no GitHub pelo hashtag #markitdown-plugin. Para desenvolver um plugin, veja packages/markitdown-sample-plugin.
Plugin markitdown-ocr
O plugin markitdown-ocr adiciona suporte a OCR aos conversores de PDF, DOCX, PPTX e XLSX, extraindo texto de imagens incorporadas usando LLM Vision — o mesmo padrão llm_client / llm_model que MarkItDown já usa para descrições de imagem. Nenhuma nova biblioteca ML ou dependência binária necessária.
Instalação:
pip install markitdown-ocr
pip install openai # or any OpenAI-compatible client
Uso:
Passar o mesmo llm_client e llm_model que você usaria para descrições de imagens:
from markitdown import MarkItDown
from openai import OpenAI
md = MarkItDown(
enable_plugins=True,
llm_client=OpenAI(),
llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.text_content)
Se nenhum llm_client for fornecido, o plugin ainda carrega, mas o OCR é silenciosamente ignorado e o conversor padrão embutido é usado em vez disso.
Veja packages/markitdown-ocr/README.md para documentação detalhada.
Azure Content Understanding
Azure Content Understanding oferece conversão de maior qualidade com extração estruturada de campos (YAML front matter), suporte multi-modal (documentos, imagens, áudio e vídeo) e analisadores configuráveis.
Instalação: pip install 'markitdown[az-content-understanding]'
Quando usar o Content Understanding
O Content Understanding é ideal quando você precisa de capacidades além do que os conversores nativos ou da Document Intelligence fornecem:
- Arquivos de áudio e vídeo — O CU (Content Understanding) é a única opção para vídeos, e a opção em nuvem de maior qualidade para áudios. Os conversores nativos não têm suporte a vídeo e oferecem apenas transcrição básica de áudio.
- Extração estruturada de campos — Analisadores pré-fabricados ou personalizados extraem campos específicos de domínio (valores em faturas, datas de recibos, cláusulas contratuais), serializados como YAML front matter. Nem os conversores nativos nem a integração com Doc Intel expõem esses campos.
- Extração de documentos de maior qualidade — Análise de layout e OCR baseados na nuvem para PDFs digitalizados, tabelas complexas e documentos multi-página.
- Uma única API para todos os modais — Um único
cu_endpointlida com documentos, imagens, áudio e vídeo com roteamento automático do analisador.
| Capacidade | Conversores nativos | Azure Document Intelligence | Azure Content Understanding |
|---|---|---|---|
| Conversão de documento | Extração offline específica por formato | Extração de layout em nuvem | Extração multi-modal em nuvem |
| Campos estruturados | Não disponível | Não exposto nesta integração | YAML front matter a partir dos campos do analisador |
| Analisadores personalizados | Não disponíveis | Não configuráveis nesta integração | Suportado com cu_analyzer_id |
| Áudio e vídeo | Áudio básico, sem vídeo | Não suportado | Analisadores de áudio e vídeo |
| Custo | Apenas computação local | Chamadas à API da Azure cobráveis | Chamadas à API da Azure cobráveis |
CLI:
markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"
API Python:
from markitdown import MarkItDown
# Zero-config — auto-selects analyzer per file type
md = MarkItDown(cu_endpoint="<content_understanding_endpoint>")
result = md.convert("report.pdf") # documents → prebuilt-documentSearch
result = md.convert("meeting.mp4") # video → prebuilt-videoSearch
result = md.convert("call.wav") # audio → prebuilt-audioSearch
print(result.markdown)
Com um analisador personalizado (para extração de campos específicos de domínio):
md = MarkItDown(
cu_endpoint="<content_understanding_endpoint>",
cu_analyzer_id="my-invoice-analyzer",
)
result = md.convert("invoice.pdf")
print(result.markdown)
# Output includes YAML front matter with extracted fields:
# ---
# contentType: document
# fields:
# VendorName: CONTOSO LTD.
# InvoiceDate: '2019-11-15'
# ---
# <!-- page 1 -->
# ...
Quando cu_analyzer_id é definido, o conversor automaticamente limita seu escopo aos tipos de arquivo compatíveis com base na modalidade do analisador. Tipos incompatíveis (por exemplo, arquivos de áudio com um analisador de documentos) são roteados automaticamente para os analisadores pré-fabricados padrão.
Nota sobre custo: Cada chamada convert() para um formato roteado pelo CU é uma chamada à API da Azure cobrável. Use cu_file_types para restringir quais formatos serão roteados ao CU:
from markitdown.converters import ContentUnderstandingFileType
md = MarkItDown(
cu_endpoint="<content_understanding_endpoint>",
cu_file_types=[ContentUnderstandingFileType.PDF], # only PDFs use CU
)
Mais informações sobre o Azure Content Understanding podem ser encontradas aqui.
Azure Document Intelligence
Para usar a Microsoft Document Intelligence na conversão:
markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"
Mais informações sobre como configurar um recurso de Azure Document Intelligence podem ser encontradas aqui
API Python
Uso básico em Python:
from markitdown import MarkItDown
md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.text_content)
Conversão de Document Intelligence em Python:
from markitdown import MarkItDown
md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)
Para usar Modelos de Linguagem Grande (LLMs) para descrições de imagens (atualmente apenas para arquivos pptx e imagem), forneça llm_client e llm_model:
from markitdown import MarkItDown
from openai import OpenAI
client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.text_content)
Docker
docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md
Contribuindo
Este projeto aceita contribuições e sugestões. A maioria das contribuições requer que você concorde com um Acordo de Licença de Contribuidor (CLA) declarando que tem o direito de, e realmente faz, conceder-nos o direito de usar sua contribuição. Para detalhes, visite https://cla.opensource.microsoft.com.
Quando você enviar uma solicitação pull (pull request), um bot CLA determinará automaticamente se você precisa fornecer um CLA e decorará a PR adequadamente (por exemplo, verificação de status, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.
Este projeto adotou o Código de Conduta de Código Aberto da Microsoft. Para mais informações, veja a FAQ do Código de Conduta ou entre em contato com opencode@microsoft.com com quaisquer perguntas adicionais ou comentários.
Como Contribuir
Você pode ajudar analisando issues ou ajudando a revisar PRs (Pull Requests). Qualquer issue ou PR é bem-vindo, mas também marcamos alguns como 'abertos para contribuição' e 'abertos para revisão' para facilitar contribuições da comunidade. Estes são apenas sugestões e você é bem-vindo a contribuir de qualquer maneira que desejar.
| Todos | Especialmente Precisa Ajuda da Comunidade | |
|---|---|---|
| Issues | Todas as Issues | Issues abertas para contribuição |
| PRs | Todos os PRs | PRs abertas para revisão |
Executando Testes e Verificações
-
Navegue até o pacote MarkItDown:
cd packages/markitdown -
Instale
hatchno seu ambiente e execute os testes:pip install hatch # Outras formas de instalar hatch: https://hatch.pypa.io/dev/install/ hatch shell hatch test(Alternativa) Use o Devcontainer que já possui todas as dependências instaladas:
# Reabra o projeto no Devcontainer e execute: hatch test -
Execute verificações pre-commit antes de enviar um PR:
pre-commit run --all-files
Considerações de Segurança
O MarkItDown realiza I/O com as permissões do processo atual. Como open() ou requests.get(), ele acessa recursos aos quais o próprio processo tem acesso.
Limpe seus inputs: Não passe entradas não confiáveis diretamente para o MarkItDown. Se qualquer parte da entrada puder ser controlada por um usuário ou sistema não confiável, como em aplicações hospedadas ou de lado do servidor, ela deve ser validada e restringida antes de chamar o MarkItDown. Dependendo do seu ambiente, isso pode incluir restringir caminhos de arquivos, limitar esquemas URI e destinos de rede, e bloquear acesso a endereços privados, loopback, link-local ou de serviços de metadados.
Chame apenas o método de conversão necessário: Prefira a API de conversão mais restrita que se encaixe no seu caso de uso. O método convert() do MarkItDown é intencionalmente permissivo e pode lidar com arquivos locais, URIs remotos e streams de bytes. Se sua aplicação só precisa ler arquivos locais, chame convert_local(). Se você precisar ter mais controle sobre a obtenção de URIs, chame requests.get() por conta própria e passe o objeto de resposta para convert_response(). Para controle máximo, abra um stream na entrada que deseja converter e chame convert_stream().
Contribuindo com Plugins de Terceiros
Você também pode contribuir criando e compartilhando plugins de terceiros. Veja packages/markitdown-sample-plugin para mais detalhes.
Marcas Registradas
Este projeto pode conter marcas registradas ou logotipos de projetos, produtos ou serviços. O uso autorizado das marcas registradas ou logotipos da Microsoft está sujeito a e deve seguir Guia de Marca & Identidade Visual da Microsoft. O uso de marcas registradas ou logotipos da Microsoft em versões modificadas deste projeto não pode causar confusão nem implicar patrocínio pela Microsoft. Qualquer uso de marcas registradas ou logotipos de terceiros está sujeito às políticas desses terceiros.