Tesseract OCR em Python
com pytesseract.
Guia completo e testado do pytesseract: instalação, API principal, pré-processamento de imagens, PDF, pontuações de confiança, configuração PSM/OEM, desempenho e os erros mais comuns.
Início rápido (três linhas)
Instale o motor primeiro e execute isto. A configuração completa vem a seguir.
import pytesseract
from PIL import Image
text = pytesseract.image_to_string(Image.open("image.png"))
print(text)Instalar o pytesseract
pytesseract é apenas um wrapper: ele chama o binário do Tesseract, então instale o motor primeiro.
pip install pytesseract pillow
# opcional, para pré-processamento:
pip install opencv-python numpy
# opcional, para entrada PDF:
pip install pdf2imageSe o motor não estiver no seu PATH (comum no Windows), aponte explicitamente:
import pytesseract
pytesseract.pytesseract.tesseract_cmd = r"C:\Program Files\Tesseract-OCR\tesseract.exe"Novo no motor? Veja o guia de instalação para Windows, macOS, Linux, Docker e WSL.
API principal
O pytesseract expõe uma função por tipo de saída. Escolha a que corresponde ao que você precisa.
| Função | Retorna | Use quando |
|---|---|---|
image_to_string | Texto simples | Você só precisa do texto reconhecido |
image_to_data | Caixas por palavra + confiança | Destacar texto, filtrar palavras de baixa confiança |
image_to_boxes | Caixas por caractere | Geometria em nível de caractere |
image_to_pdf_or_hocr | PDF pesquisável ou hOCR | Criar PDFs pesquisáveis ou overlays web |
image_to_osd | Detecção de orientação e escrita | Detectar rotação ou escrita antes do OCR |
image_to_alto_xml | ALTO XML | Pipelines de arquivo / bibliotecas |
Configuração: PSM, OEM, idiomas e lista de caracteres
Passe as opções como uma string separada por espaços para config=.
# Um único bloco de texto, motor LSTM, português
text = pytesseract.image_to_string(img, lang="por", config="--oem 3 --psm 6")
# Somente dígitos (totais de recibos, leituras de medidores)
text = pytesseract.image_to_string(img, config="--psm 7 -c tessedit_char_whitelist=0123456789.")
# Idiomas combinados
text = pytesseract.image_to_string(img, lang="eng+por")| PSM | Modo | Ideal para |
|---|---|---|
| 3 | Totalmente automático (padrão) | Documentos padrão |
| 4 | Uma coluna de tamanhos variáveis | Artigos, páginas de uma coluna |
| 6 | Um bloco uniforme de texto | Parágrafos, etiquetas |
| 7 | Uma única linha de texto | Legendas de uma linha, campos isolados |
| 8 | Uma única palavra | Palavras individuais |
| 11 | Texto esparso | Recibos, texto de interface espalhado |
| 13 | Linha bruta | Uma linha sem truques específicos |
Modos OEM: --oem 1 (somente LSTM, padrão na v5), --oem 0 (legado), --oem 3 (automático). Referência completa na documentação.
Pré-processamento de imagens
Uma entrada limpa é o maior fator de precisão. Estes são os passos que mais importam.
import cv2, numpy as np, pytesseract
from PIL import Image
image = cv2.imread("recibo.jpg")
gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
# Amplie o texto pequeno para ~300 DPI equivalentes
gray = cv2.resize(gray, None, fx=2, fy=2, interpolation=cv2.INTER_CUBIC)
# Remova ruído e aplique limiar de Otsu para preto e branco puro
blur = cv2.GaussianBlur(gray, (5, 5), 0)
_, binary = cv2.threshold(blur, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
text = pytesseract.image_to_string(Image.fromarray(binary))- Escala de cinza — remova os canais de cor antes do limiar.
- Ampliação — texto com menos de ~20 px é reconhecido mal; amplie.
- Limiar — Otsu com luz uniforme, adaptativo com luz irregular.
- Remoção de ruído — um desfoque leve remove manchas lidas como pontuação.
- Alinhamento — corrija a rotação com
cv2.minAreaRectantes do OCR. - Corte de bordas — remova bordas escuras que confundem a análise de layout.
Posições e pontuações de confiança
Use image_to_data para obter caixas por palavra e uma confiança de 0 a 100, e filtre o ruído.
from pytesseract import Output
data = pytesseract.image_to_data(img, output_type=Output.DICT)
for text, conf in zip(data["text"], data["conf"]):
if text.strip() and float(conf) > 60: # descarta ruído de baixa confiança
print(round(float(conf)), text)OCR de um PDF em Python
O Tesseract trabalha com imagens, então rasterize as páginas do PDF primeiro com pdf2image (que requer as ferramentas poppler).
import io, pytesseract
from pdf2image import convert_from_path
from pypdf import PdfWriter, PdfReader
pages = convert_from_path("digitalizado.pdf", dpi=300) # requer poppler
writer = PdfWriter()
for page in pages:
pdf_bytes = pytesseract.image_to_pdf_or_hocr(page, extension="pdf")
writer.add_page(PdfReader(io.BytesIO(pdf_bytes)).pages[0])
with open("digitalizado_pesquisavel.pdf", "wb") as f:
writer.write(f)No Windows, passe a pasta bin do poppler com poppler_path=. Para um fluxo mais completo, veja a documentação sobre formatos de saída.
Desempenho
O pytesseract chama a CLI a cada chamada, então o desempenho depende de como você estrutura o processo.
| Abordagem | Quando | Compromisso |
|---|---|---|
pytesseract por chamada | Scripts e tarefas pontuais | Inicia um processo por chamada — lento em laços |
| Agrupar em TIFF multipágina | Muitas páginas com as mesmas opções | Um processo para muitas páginas |
multiprocessing | Muitas imagens independentes | Usa todos os núcleos; mais memória |
tesserocr | Alto volume, em processo | Binding nativo, mais configuração |
Catálogo de erros
Estes erros cobrem a maioria dos problemas com o pytesseract.
| Erro | Causa | Correção |
|---|---|---|
TesseractNotFoundError | Binário não instalado ou fora do PATH | Instale o motor ou defina pytesseract.pytesseract.tesseract_cmd. |
(-215:Assertion failed) src.type() == CV_8UC1 | Limiar em imagem de 3 canais | Converta com cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) primeiro. |
Error opening data file ...fra.traineddata | Pacote de idioma ausente | Instale o idioma ou defina TESSDATA_PREFIX. |
| Saída vazia | DPI baixo, PSM errado ou sem texto | Amplie, teste --psm 6/7/11 e pré-processe. |
| Muito lento em laço | Um processo por chamada | Agrupe, use multiprocessing ou tesserocr. |
Medir a precisão
Meça a taxa de erro de caracteres e palavras em vez de avaliar a saída a olho.
import pytesseract, jiwer
from PIL import Image
hypothesis = pytesseract.image_to_string(Image.open("amostra.png"))
reference = open("amostra.gt.txt").read()
print("CER:", jiwer.cer(reference, hypothesis))
print("WER:", jiwer.wer(reference, hypothesis))Mantenha um pequeno conjunto de imagens representativas com texto de referência como testes de regressão e reexecute ao mudar o pré-processamento ou a configuração.
Perguntas frequentes de Python
Como uso o Tesseract OCR em Python?
Instale primeiro o motor Tesseract e depois pip install pytesseract pillow. Abra a imagem com o Pillow e chame pytesseract.image_to_string(img).
Por que recebo TesseractNotFoundError?
O pytesseract não encontra o binário. Instale o motor, coloque-o no PATH ou defina pytesseract.pytesseract.tesseract_cmd com o caminho completo.
Como melhoro a precisão?
Escale a ~300 DPI, escala de cinza, limiar, remoção de ruído, alinhamento e o --psm correto. Use o lang= adequado e, para campos fixos, uma lista de caracteres permitidos.
Como faço OCR de um PDF?
Use pdf2image (com poppler) para converter as páginas em imagens, rode o pytesseract em cada uma e combine com image_to_pdf_or_hocr(..., extension="pdf").
Como obtenho pontuações de confiança?
Use image_to_data(..., output_type=Output.DICT) e filtre pela lista conf.
O pytesseract é lento?
Cada chamada inicia um processo. Agrupe, use multiprocessing ou mude para o binding em processo tesserocr para alto desempenho.
Próximos passos
Aprofunde-se no motor e no ecossistema.