# How to Process Only Specific Pages of a PDF with pdf-inspector

> Easily process specific PDF pages with pdf-inspector. Learn how to use the pages option in PdfOptions or the --pages flag in the pdf2md CLI for targeted PDF processing.

- Repository: [Firecrawl/pdf-inspector](https://github.com/firecrawl/pdf-inspector)
- Tags: how-to-guide
- Published: 2026-08-13

---

**To extract specific pages from a PDF using pdf-inspector, configure the `pages` field in `PdfOptions` when calling `process_pdf_with_options`, or pass the `--pages` flag to the `pdf2md` CLI.**

The `pdf-inspector` library from Firecrawl provides precise control over PDF extraction through its configuration structs. When you need to process only specific pages of a PDF with pdf-inspector, you can leverage the `pages` vector to filter content before conversion to Markdown or JSON, avoiding the overhead of parsing unwanted pages.

## Programmatic Page Selection with PdfOptions

The core mechanism resides in [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs), where the `PdfOptions` struct exposes a `pages` field. This field accepts a `Vec<u32>` containing 1-based page numbers that instruct the extractor to skip all other pages during processing.

When calling `process_pdf_with_options`, instantiate `PdfOptions` and populate the `pages` vector with your target indices:

```rust
use pdf_inspector::{process_pdf_with_options, PdfOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Specify exact pages to extract (1-based indexing)
    let opts = PdfOptions::new()
        .pages(vec![2, 4, 5]);

    let result = process_pdf_with_options("document.pdf", opts)?;
    println!("{}", result.markdown);
    Ok(())
}

```

Internally, the extraction logic in [`src/extractor/mod.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/extractor/mod.rs) checks this filter before processing each page, ensuring only the specified content reaches the output pipeline.

## CLI Page Filtering with pdf2md

For command-line usage, the `pdf2md` binary defined in [`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) exposes a `--pages` argument. The parser converts comma-separated values and range expressions—such as `1-3,5`—into the `Vec<u32>` expected by `PdfOptions`.

Execute selective extraction via:

```bash

# Extract a single page

pdf2md --pages 7 report.pdf

# Extract pages 1 through 3 plus page 9

pdf2md --pages 1-3,9 report.pdf > excerpt.md

```

This CLI implementation builds the same `PdfOptions` struct used in the library API, maintaining consistent behavior across interfaces.

## How Page Filtering Works Under the Hood

The page restriction logic operates at the orchestration layer within the extractor. When `process_pdf_with_options` receives a `PdfOptions` instance with the `pages` field populated, the engine iterates only over the specified indices instead of the full document range. This early filtering prevents resource-intensive parsing operations on excluded pages, significantly improving performance for large documents when you need only specific sections.

## Summary

- **`PdfOptions.pages`**: Pass a `Vec<u32>` of 1-based page numbers to `process_pdf_with_options` in [`src/lib.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/lib.rs) to limit extraction programmatically.
- **CLI convenience**: The `pdf2md` binary in [`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) accepts `--pages` with comma-separated values or ranges (e.g., `2-4,7`).
- **Performance benefit**: Page filtering occurs early in the extraction pipeline, preventing unnecessary parsing of skipped content.
- **Consistent behavior**: Both Rust and CLI interfaces leverage the same underlying validation logic in [`src/extractor/mod.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/extractor/mod.rs).

## Frequently Asked Questions

### How do I specify page ranges in the pdf-inspector CLI?

The `pdf2md` CLI supports range expressions within the `--pages` flag. Specify ranges with a hyphen and separate multiple selections with commas, such as `--pages 1-3,5,8-10`. The parser in [`src/bin/pdf2md.rs`](https://github.com/firecrawl/pdf-inspector/blob/main/src/bin/pdf2md.rs) expands these ranges into individual page numbers before constructing the `PdfOptions` struct.

### Can I process non-consecutive pages with the Rust API?

Yes. The `pages` field in `PdfOptions` accepts any `Vec<u32>`, allowing you to specify arbitrary, non-sequential page orders. For example, `vec![1, 5, 10, 12]` extracts only those specific pages regardless of their position in the document.

### What happens if I provide an invalid page number?

The extractor validates page numbers against the total page count during processing. If the `pages` vector contains a number exceeding the document's length, the operation returns an error indicating the requested page is out of bounds.

### Is page indexing 0-based or 1-based in pdf-inspector?

pdf-inspector uses **1-based indexing** for the `pages` vector, matching standard document conventions where the first page is page 1. When constructing `PdfOptions` or using the `--pages` CLI flag, always reference pages starting at 1.