MarkItDown da Microsoft: Converta PDF e Word com Python

MarkItDown é a biblioteca open source da Microsoft para converter PDF, Word, Excel, PowerPoint, HTML e outros arquivos em Markdown com Python. Instale com pip install "markitdown[all]", use MarkItDown().convert("arquivo.pdf") e leia o resultado em text_content. A ferramenta é especialmente útil para preparar documentos para LLMs, RAG, busca e automação.

Neste guia, você aprende a instalar o MarkItDown, usar a API e a linha de comando, converter os principais formatos e decidir quando uma biblioteca especializada é melhor. Se o seu problema é somente PDF, compare também as opções do guia de extração de texto com pypdf e pdfplumber. Para arquivos editáveis do Word, veja python-docx.

Por que Markdown para LLMs?

Modelos como GPT-4o, Claude e Gemini “falam” Markdown nativamente. Quando você envia um documento em Markdown para um LLM, o modelo consegue entender a hierarquia de títulos, tabelas, listas e links sem precisar de parsing adicional.

O problema é que a maioria dos dados corporativos está em formatos binários — PDF, DOCX, XLSX, PPTX. Converter esses formatos para texto puro perde a estrutura. Converter para Markdown preserva a estrutura de forma que o LLM consegue interpretar.

É aí que o MarkItDown entra: ele pega um arquivo em qualquer formato suportado e gera Markdown limpo, com tabelas, cabeçalhos e formatação preservados.

Instalação

O MarkItDown está disponível no PyPI. Se você usa pip ou uv, a instalação é direta:

# Instalação básica
python -m pip install markitdown

# Com suporte aos formatos opcionais
python -m pip install "markitdown[all]"

# Com uv
uv add "markitdown[all]"

O pacote [all] inclui dependências para PDF, áudio, imagens e outros formatos que precisam de bibliotecas extras.

Uso básico: convertendo arquivos

A API do MarkItDown é simples — um conversor e um método convert:

from markitdown import MarkItDown

conversor = MarkItDown()

# Converter um arquivo PDF
resultado = conversor.convert("relatorio-financeiro.pdf")
print(resultado.text_content)

O retorno é um objeto com o atributo text_content contendo o Markdown gerado. Vamos ver exemplos com diferentes formatos.

Convertendo documentos Word (DOCX)

resultado = conversor.convert("proposta-comercial.docx")
print(resultado.text_content)

Saída típica:

# Proposta Comercial — Projeto Alpha

## Escopo do Projeto

O projeto Alpha visa implementar um sistema de...

## Cronograma

| Fase | Início | Término | Responsável |
|------|--------|---------|-------------|
| Descoberta | 01/05/2026 | 15/05/2026 | Equipe A |
| Desenvolvimento | 16/05/2026 | 30/07/2026 | Equipe B |

Note como tabelas, títulos e formatação são preservados como Markdown válido.

Convertendo planilhas Excel (XLSX)

resultado = conversor.convert("vendas-q1-2026.xlsx")
print(resultado.text_content)

O MarkItDown converte cada aba da planilha em uma seção com tabelas Markdown. Isso é extremamente útil para análise de dados com LLMs — em vez de usar pandas para processar e depois explicar os dados, você pode enviar a planilha direto para o modelo.

Convertendo apresentações PowerPoint (PPTX)

resultado = conversor.convert("apresentacao-resultados.pptx")
print(resultado.text_content)

Cada slide vira uma seção, com textos, bullet points e notas do apresentador preservados. Imagens nos slides recebem descrições quando integrado com um modelo de visão.

Convertendo PDFs

resultado = conversor.convert("contrato-servicos.pdf")
print(resultado.text_content)

PDFs são o formato mais desafiador por causa da variedade de estruturas internas. O MarkItDown usa heurísticas para detectar títulos, parágrafos e tabelas, mas PDFs escaneados (imagens) precisam de OCR adicional.

Convertendo páginas HTML e URLs

Além de arquivos locais, o MarkItDown converte HTML e até busca URLs diretamente:

# HTML local
resultado = conversor.convert("pagina.html")

# URL remota
resultado = conversor.convert("https://python.dev.br/blog/")
print(resultado.text_content)

Isso é útil para web scraping onde você quer o conteúdo em Markdown limpo, sem precisar parsear HTML manualmente com BeautifulSoup.

Integração com LLMs para descrição de imagens

Uma funcionalidade que diferencia o MarkItDown é a integração com modelos de visão para descrever imagens automaticamente:

from openai import OpenAI

cliente = OpenAI()

conversor = MarkItDown(
    llm_client=cliente,
    llm_model="gpt-4o-mini",
)

# Converter imagem com descrição gerada por IA
resultado = conversor.convert("grafico-vendas.png")
print(resultado.text_content)
# Saída: "Gráfico de barras mostrando vendas mensais de janeiro a março de 2026..."

Quando o MarkItDown encontra uma imagem (seja um arquivo direto ou embutida em um PPTX/DOCX), ele envia para o modelo de visão e inclui a descrição no Markdown gerado. Para quem trabalha com processamento de imagens, essa integração elimina uma etapa manual.

Uso na linha de comando

O MarkItDown também funciona como ferramenta CLI, útil para automação com scripts:

# Converter arquivo único
markitdown relatorio.pdf > relatorio.md

# Converter com saída no terminal
markitdown apresentacao.pptx

Se você gosta de criar ferramentas de linha de comando, pode integrar o MarkItDown em seus próprios scripts facilmente.

Pipeline prático: RAG com documentos corporativos

Um caso de uso real é construir um sistema de Retrieval-Augmented Generation (RAG) que indexa documentos da empresa. Veja um pipeline simplificado:

from markitdown import MarkItDown
from pathlib import Path

conversor = MarkItDown()

def processar_documentos(pasta: str) -> list[dict]:
    """Converte todos os documentos de uma pasta para Markdown."""
    documentos = []
    formatos_suportados = {".pdf", ".docx", ".xlsx", ".pptx", ".html"}

    for arquivo in Path(pasta).rglob("*"):
        if arquivo.suffix.lower() in formatos_suportados:
            try:
                resultado = conversor.convert(str(arquivo))
                documentos.append({
                    "nome": arquivo.name,
                    "caminho": str(arquivo),
                    "conteudo": resultado.text_content,
                    "formato": arquivo.suffix,
                })
                print(f"Convertido: {arquivo.name}")
            except Exception as e:
                print(f"Erro em {arquivo.name}: {e}")

    return documentos

# Processar pasta de documentos
docs = processar_documentos("/home/diego/documentos/empresa")
print(f"Total convertido: {len(docs)} documentos")

Depois de converter, você pode usar os textos Markdown para criar embeddings, indexar em um banco vetorial e construir um chatbot que responde perguntas sobre seus documentos — tudo usando Python e JSON para armazenar os metadados.

Processamento em lote com tratamento de erros

Para produção, é importante tratar erros e logging adequadamente:

import logging
from markitdown import MarkItDown

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

conversor = MarkItDown()

def converter_com_fallback(caminho: str) -> str | None:
    """Converte arquivo com tratamento de erros robusto."""
    try:
        resultado = conversor.convert(caminho)
        if not resultado.text_content or len(resultado.text_content.strip()) < 10:
            logger.warning(f"Conteúdo vazio ou muito curto: {caminho}")
            return None
        logger.info(f"Convertido com sucesso: {caminho} ({len(resultado.text_content)} chars)")
        return resultado.text_content
    except FileNotFoundError:
        logger.error(f"Arquivo não encontrado: {caminho}")
    except PermissionError:
        logger.error(f"Sem permissão para ler: {caminho}")
    except Exception as e:
        logger.error(f"Erro ao converter {caminho}: {type(e).__name__}: {e}")
    return None

Comparação com alternativas

O grande diferencial do MarkItDown é a simplicidade: uma API unificada para vários formatos, com saída em Markdown. Bibliotecas especializadas ainda são melhores quando você precisa editar documentos, alterar células de uma planilha ou controlar detalhes da extração. O unstructured oferece mais opções de particionamento e pipelines, mas exige uma configuração mais complexa.

Limitações e cuidados

Nem tudo são flores. Alguns pontos de atenção:

• PDFs escaneados — o MarkItDown não faz OCR nativo; você precisa de ferramentas adicionais como Tesseract
• Tabelas complexas — tabelas com células mescladas ou layouts irregulares podem perder estrutura
• Arquivos grandes — documentos com centenas de páginas podem consumir bastante memória
• Dados sensíveis — ao usar a integração com LLMs para imagens, os dados são enviados para a API do provedor

Para arquivos grandes, considere processar em chunks ou usar multiprocessing para paralelizar a conversão.

Quando usar o MarkItDown

O MarkItDown brilha em cenários como:

• Pipelines de RAG — indexar documentos corporativos para chatbots internos
• Automação de relatórios — converter relatórios de diferentes formatos para um padrão unificado
• Pré-processamento para LLMs — preparar dados para fine-tuning ou análise
• Migração de conteúdo — converter documentação legada para Markdown

Perguntas frequentes

O que é o MarkItDown da Microsoft?

É uma biblioteca Python open source que transforma documentos em Markdown. Ela oferece uma interface única para extrair conteúdo de PDF, DOCX, XLSX, PPTX, HTML, imagens e outros formatos, o que facilita preparar dados para busca, RAG e LLMs.

Como instalar o MarkItDown no Python?

Crie um ambiente virtual e rode python -m pip install "markitdown[all]". O extra all instala recursos opcionais; em projetos mais enxutos, você pode instalar somente o pacote básico ou os extras necessários.

Como converter PDF para Markdown?

Use resultado = MarkItDown().convert("arquivo.pdf") e acesse resultado.text_content. Na CLI, execute markitdown arquivo.pdf > arquivo.md. Se o PDF for apenas uma imagem digitalizada, adicione OCR ao pipeline.

MarkItDown substitui pypdf, python-docx e openpyxl?

Não completamente. Escolha MarkItDown para extrair conteúdo heterogêneo por uma API comum. Use bibliotecas especializadas para editar Word ou Excel e para controlar a extração de PDF em detalhes.

O MarkItDown funciona sem enviar dados para um LLM?

Sim. A conversão comum funciona localmente. O cliente de LLM é opcional, por exemplo para gerar descrições de imagens. Ao ativá-lo, verifique quais dados serão enviados ao provedor.

Conclusão

O MarkItDown oferece uma forma prática de converter documentos para Markdown com uma API Python e uma CLI consistentes. Ele funciona melhor como camada de extração para automação, indexação e pipelines de IA; para edição ou parsing especializado, combine-o com bibliotecas próprias de cada formato.

Se você quer explorar mais sobre automação de documentos, confira nosso guia de Python e Excel e como trabalhar com manipulação de arquivos. E para quem quer criar agentes de IA que usam MarkItDown como ferramenta, o artigo sobre LangGraph e agentes é o próximo passo natural.

Desenvolvedores que usam Kotlin para projetos Android podem se interessar por como o ecossistema mobile se integra com backends Python em kotlin.dev.br. Para quem explora Rust em ferramentas de alta performance como o próprio ruff e uv, vale visitar rustlang.com.br.