Parse Documents to Markdown with Python
Parse PDF, Word, Excel, and PowerPoint files in Python with BulkParse. Save Markdown, inspect diagnostics, handle errors, and use the hosted Bulkgrid API.

A document ingestion script needs more than a text string. It needs to know which file was processed, what was extracted, and whether any content needs review.
BulkParse provides a Python interface to its Rust document parser. You can convert supported files locally into Markdown and a structured document model. This guide starts with one file, adds diagnostics and error handling, and shows the separate hosted option through Bulkgrid.
Install BulkParse
Use Python 3.10 or newer. Install the package in your project's virtual environment:
python -m pip install bulkparsePrebuilt wheels are available for supported platforms. A source build requires Rust; check the Python installation guide for platform coverage and build instructions.
The local parser does not require a Bulkgrid account or API key. Installing the package may access a package registry; ordinary native conversion does not send the document to an external parsing service.
Parse a local document and save Markdown
Place a Word document named report.docx beside your script, or replace that path with a supported file:
from pathlib import Path
from bulkparse import parse_file
result = parse_file("report.docx")
with Path("report.md").open("x", encoding="utf-8") as output:
output.write(result["markdown"])
print("Status:", result["status"])
print("Diagnostics:", result["diagnostics"])
print("Rendering diagnostics:", result["render_diagnostics"])The exclusive write mode prevents the example from overwriting an existing report.md. Choose another output path when rerunning it.
Use result["markdown"] for readable content and result["document"]["blocks"] when your application needs the structured representation. Keep the original filename and available source references with the output so that extracted passages can be traced back.
Parse bytes instead of a path
When your application already holds a bounded byte buffer, use parse and provide the original filename:
from bulkparse import parse
result = parse(
b"# Hello\n\nA small document",
filename="hello.md",
)
print(result["markdown"])The same interface accepts supported binary document bytes. Passing a PDF's bytes does not mean you should decode them as UTF-8 first. Let the parser read the original binary format.
For web uploads, enforce request-size limits before retaining the full file in application memory.
Decide what partial output means for your application
A partial result can contain useful content alongside limitations. Inspect status, diagnostics, render_diagnostics, and coverage. Diagnostics distinguish kinds of issues, including missing content, formatting limitations, and informational notices.
Native PDF conversion currently reports partial coverage by design. Automatically discarding every partial result would therefore discard useful PDF text too. Your acceptance rule should reflect the task: a search preview may tolerate a formatting gap, while a table used for calculations needs closer verification.
For workflows that must reject partial conversion, use strict mode:
from bulkparse import BulkParseError, parse_file
try:
result = parse_file("report.docx", strict=True)
except BulkParseError as error:
print(f"Parsing failed [{error.code}]: {error}")
except OSError as error:
print(f"Could not read the input: {error}")
else:
print(result["markdown"])BulkParseError exposes stable error categories such as unsupported, malformed, resource_limit, and incomplete. Strict mode rejects partial results; it does not guarantee perfect extraction of every document feature.
Inspect PDFs before adding OCR
PDF inspection works without an OCR runtime:
from pathlib import Path
from bulkparse import inspect_pdf
inspection = inspect_pdf(Path("report.pdf").read_bytes())
print(inspection)The example is for a local file you have already size-checked. Inspection reports page classifications and OCR-routing recommendations, but does not recognize text from scans.
For scanned PDFs or standalone images, follow the OCR binding guide. Native OCR needs additional libraries and models. Ordinary parse_file is not a substitute for provisioning and invoking that OCR path.
Process documents with bounded concurrency
Python conversion calls are synchronous and release the GIL while the native conversion runs. An async web handler should avoid doing the synchronous work directly on its event-loop thread.
Start with sequential conversion or a bounded worker queue. Limit queued input bytes as well as worker count. For untrusted files, use process isolation and operating-system resource limits; parser budgets are not a hard memory or CPU sandbox.
Save each file's result and failure independently. This makes a batch resumable without reparsing every successful document.
Use hosted parsing with Bulkgrid
If you prefer managed processing, install the separate Bulkgrid SDK:
python -m pip install bulkgridConfigure BULKGRID_API_KEY in your server environment with parse:write and runs:read scopes, then run:
import os
from bulkgrid import BulkgridClient
with BulkgridClient(api_key=os.environ["BULKGRID_API_KEY"]) as client:
document = client.parse("./report.pdf")
print(document["markdown"])
print(document["metadata"]["pageCount"])This uploads the file to Bulkgrid, starts a parse run, waits for completion, and retrieves Markdown. It is a hosted workflow, unlike local BulkParse. Hosted Parse supports automatic OCR for supported scanned PDFs and images, and parsing alone does not add the file to an index.
The default helper waits for up to 300 seconds. A wait timeout does not cancel the server run. For durable jobs, use start_parse, save the returned run ID, and resume with wait_for_parse instead of uploading the document again.
Try a file in the Parse playground. For format-specific advice, see PDF to Markdown, Word to Markdown, and the hosted Parse API documentation.