Merge and Split PDFs in Python, Rust, Go

Binding coverage. PDF merge is available in Python, Rust, and Go. Splitting to a file via extract_pages is Python + Rust; the in-memory extract_pages_to_bytes variant adds Swift and the C ABI (not WASM). Bookmark-based split planning (plan_split_by_bookmarks) is available in Python, Rust, Swift, WASM, and the C ABI. For the file-splitting bindings the C# binding does not yet expose these editor operations — use the Rust CLI (pdf-oxide merge, pdf-oxide split) as a workaround, or call through one of the supported bindings.

Merge two PDFs into one:

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("main.pdf")
doc.merge_from("appendix.pdf")
doc.save("combined.pdf")

WASM

import { WasmPdfDocument } from "pdf-oxide-wasm";

// Load both PDFs as Uint8Array
const mainDoc = new WasmPdfDocument(mainBytes);
const appendixDoc = new WasmPdfDocument(appendixBytes);
// Extract text from both and process as needed
const allText = mainDoc.extractAllText() + "\n" + appendixDoc.extractAllText();
mainDoc.free();
appendixDoc.free();

Rust

use pdf_oxide::editor::DocumentEditor;

let mut editor = DocumentEditor::open("main.pdf")?;
editor.merge_from("appendix.pdf")?;
editor.save("combined.pdf")?;

Go

package main

import (
    "log"
    pdfoxide "github.com/yfedoseev/pdf_oxide/go"
)

func main() {
    editor, err := pdfoxide.OpenEditor("main.pdf")
    if err != nil { log.Fatal(err) }
    defer editor.Close()

    if _, err := editor.MergeFrom("appendix.pdf"); err != nil { log.Fatal(err) }
    if err := editor.Save("combined.pdf"); err != nil { log.Fatal(err) }
}

C++

#include <pdf_oxide/pdf_oxide.hpp>

auto editor = pdf_oxide::DocumentEditor::open("main.pdf");
editor.merge_from("appendix.pdf");
editor.save("combined.pdf");

Swift

import PdfOxide

let editor = try DocumentEditor.open("main.pdf")
try editor.mergeFrom("appendix.pdf")
try editor.save("combined.pdf")

Dart

import 'package:pdf_oxide/pdf_oxide.dart';

final editor = DocumentEditor.open('main.pdf');
editor.mergeFrom('appendix.pdf');
editor.save('combined.pdf');

R

library(pdfoxide)

editor <- pdf_editor_open("main.pdf")
pdf_editor_merge_from(editor, "appendix.pdf")
pdf_editor_save(editor, "combined.pdf")

Julia

using PdfOxide

editor = open_editor("main.pdf")
merge_from(editor, "appendix.pdf")
save(editor, "combined.pdf")

Zig

const pdf_oxide = @import("pdf_oxide");

var editor = try pdf_oxide.DocumentEditor.openEditor("main.pdf");
defer editor.deinit();
try editor.mergeFrom("appendix.pdf");
try editor.save("combined.pdf");

Objective-C

#import "POXPdfOxide.h"
NSError *err = nil;

POXDocumentEditor *editor = [POXDocumentEditor openEditor:@"main.pdf" error:&err];
[editor mergeFrom:@"appendix.pdf" error:&err];
[editor saveToPath:@"combined.pdf" error:&err];

Elixir

{:ok, editor} = PdfOxide.open_editor("main.pdf")
:ok = PdfOxide.merge_from(editor, "appendix.pdf")
:ok = PdfOxide.editor_save(editor, "combined.pdf")

PDF Oxide handles page merging at the PDF object level — fonts, images, and annotations are preserved correctly across documents.

Installation

pip install pdf_oxide

Merge PDFs

Merge All Pages

Append every page from a second PDF to the first:

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("report.pdf")
doc.merge_from("charts.pdf")
doc.save("full-report.pdf")

WASM

// WASM API: load and process multiple documents
const report = new WasmPdfDocument(reportBytes);
const charts = new WasmPdfDocument(chartsBytes);
// Process both documents together
const fullText = report.extractAllText() + "\n" + charts.extractAllText();
report.free();
charts.free();

Rust

let mut editor = DocumentEditor::open("report.pdf")?;
let pages_added = editor.merge_from("charts.pdf")?;
println!("Added {} pages", pages_added);
editor.save("full-report.pdf")?;

Go

editor, _ := pdfoxide.OpenEditor("report.pdf")
defer editor.Close()

added, _ := editor.MergeFrom("charts.pdf")
fmt.Printf("Added %d pages\n", added)
_ = editor.Save("full-report.pdf")

C++

auto editor = pdf_oxide::DocumentEditor::open("report.pdf");
editor.merge_from("charts.pdf");
editor.save("full-report.pdf");

Swift

let editor = try DocumentEditor.open("report.pdf")
try editor.mergeFrom("charts.pdf")
try editor.save("full-report.pdf")

Dart

final editor = DocumentEditor.open('report.pdf');
editor.mergeFrom('charts.pdf');
editor.save('full-report.pdf');

R

editor <- pdf_editor_open("report.pdf")
pdf_editor_merge_from(editor, "charts.pdf")
pdf_editor_save(editor, "full-report.pdf")

Julia

editor = open_editor("report.pdf")
merge_from(editor, "charts.pdf")
save(editor, "full-report.pdf")

Zig

var editor = try pdf_oxide.DocumentEditor.openEditor("report.pdf");
defer editor.deinit();
try editor.mergeFrom("charts.pdf");
try editor.save("full-report.pdf");

Objective-C

POXDocumentEditor *editor = [POXDocumentEditor openEditor:@"report.pdf" error:&err];
[editor mergeFrom:@"charts.pdf" error:&err];
[editor saveToPath:@"full-report.pdf" error:&err];

Elixir

{:ok, editor} = PdfOxide.open_editor("report.pdf")
:ok = PdfOxide.merge_from(editor, "charts.pdf")
:ok = PdfOxide.editor_save(editor, "full-report.pdf")

Merge Multiple Files

Use the static Pdf.merge() method to combine several PDFs in one call:

Python

from pdf_oxide import Pdf

pdf = Pdf.merge(["intro.pdf", "chapter1.pdf", "chapter2.pdf", "appendix.pdf"])
pdf.save("book.pdf")

You can also chain merge_from() calls on an existing document:

from pdf_oxide import PdfDocument

doc = PdfDocument("intro.pdf")
for f in ["chapter1.pdf", "chapter2.pdf", "appendix.pdf"]:
    doc.merge_from(f)
doc.save("book.pdf")

WASM

// Load and process multiple PDFs sequentially
const files = [introBytes, ch1Bytes, ch2Bytes, appendixBytes];
const allText = [];
for (const bytes of files) {
    const doc = new WasmPdfDocument(bytes);
    allText.push(doc.extractAllText());
    doc.free();
}
console.log(allText.join("\n"));

Rust

let files = ["intro.pdf", "chapter1.pdf", "chapter2.pdf", "appendix.pdf"];
let mut editor = DocumentEditor::open(files[0])?;
for f in &files[1..] {
    editor.merge_from(f)?;
}
editor.save("book.pdf")?;

Go

// Top-level Merge returns the combined PDF bytes in one call
bytes, err := pdfoxide.Merge([]string{
    "intro.pdf", "chapter1.pdf", "chapter2.pdf", "appendix.pdf",
})
if err != nil { log.Fatal(err) }
_ = os.WriteFile("book.pdf", bytes, 0644)

C++

// Top-level merge returns the combined PDF bytes in one call
auto bytes = pdf_oxide::merge({"intro.pdf", "chapter1.pdf", "chapter2.pdf", "appendix.pdf"});
std::ofstream("book.pdf", std::ios::binary)
    .write(reinterpret_cast<const char*>(bytes.data()), bytes.size());

Swift

// Top-level merge returns the combined PDF bytes in one call
let bytes = try merge(["intro.pdf", "chapter1.pdf", "chapter2.pdf", "appendix.pdf"])
try Data(bytes).write(to: URL(fileURLWithPath: "book.pdf"))

Dart

// Top-level pdfMerge returns the combined PDF bytes in one call
final bytes = pdfMerge(['intro.pdf', 'chapter1.pdf', 'chapter2.pdf', 'appendix.pdf']);
File('book.pdf').writeAsBytesSync(bytes);

R

# Top-level pdf_merge returns the combined PDF bytes in one call
bytes <- pdf_merge(c("intro.pdf", "chapter1.pdf", "chapter2.pdf", "appendix.pdf"))
writeBin(bytes, "book.pdf")

Julia

# Top-level merge_pdfs returns the combined PDF bytes in one call
bytes = merge_pdfs(["intro.pdf", "chapter1.pdf", "chapter2.pdf", "appendix.pdf"])
write("book.pdf", bytes)

Zig

const a = std.heap.page_allocator;
const paths = [_][*:0]const u8{ "intro.pdf", "chapter1.pdf", "chapter2.pdf", "appendix.pdf" };
const bytes = try pdf_oxide.merge(a, &paths); // combined PDF bytes
defer a.free(bytes);
const out = try std.fs.cwd().createFile("book.pdf", .{});
defer out.close();
try out.writeAll(bytes);

Objective-C

// Top-level merge returns the combined PDF bytes in one call
NSData *bytes = [POXTools merge:@[@"intro.pdf", @"chapter1.pdf", @"chapter2.pdf", @"appendix.pdf"]
                          error:&err];
[bytes writeToFile:@"book.pdf" atomically:YES];

Elixir

# Top-level merge returns the combined PDF bytes in one call
{:ok, bytes} = PdfOxide.merge(["intro.pdf", "chapter1.pdf", "chapter2.pdf", "appendix.pdf"])
File.write!("book.pdf", bytes)

Merge Specific Pages

Select which pages to merge from the source document:

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("main.pdf")
# Merge only pages 0, 2, and 4 from source
doc.merge_pages_from("source.pdf", [0, 2, 4])
doc.save("selected.pdf")

Rust

let mut editor = DocumentEditor::open("main.pdf")?;
editor.merge_pages_from("source.pdf", &[0, 2, 4])?;
editor.save("selected.pdf")?;

Split PDFs

Extract Pages to a New File

Pull specific pages out of a large document:

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("book.pdf")
doc.extract_pages([0, 1, 2, 3, 4], "chapter1.pdf")

WASM

// Extract text from specific pages
const doc = new WasmPdfDocument(bytes);
const pages = [0, 1, 2, 3, 4];
for (const i of pages) {
    const text = doc.extractText(i);
    console.log(`Page ${i + 1}: ${text.slice(0, 80)}...`);
}
doc.free();

Rust

let mut editor = DocumentEditor::open("book.pdf")?;
editor.extract_pages(&[0, 1, 2, 3, 4], "chapter1.pdf")?;

Split Into Individual Pages

Save each page as a separate file:

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("document.pdf")
for i in range(doc.page_count()):
    doc.extract_pages([i], f"page_{i + 1}.pdf")

Rust

let mut editor = DocumentEditor::open("document.pdf")?;
let page_count = editor.page_count()?;
for i in 0..page_count {
    editor.extract_pages(&[i], &format!("page_{}.pdf", i + 1))?;
}

Split Into Chunks

Split a large PDF into smaller files of N pages each:

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("large.pdf")
chunk_size = 10

for start in range(0, doc.page_count(), chunk_size):
    end = min(start + chunk_size, doc.page_count())
    pages = list(range(start, end))
    doc.extract_pages(pages, f"chunk_{start // chunk_size + 1}.pdf")

Rust

let mut editor = DocumentEditor::open("large.pdf")?;
let page_count = editor.page_count()?;
let chunk_size = 10;

for start in (0..page_count).step_by(chunk_size) {
    let end = (start + chunk_size).min(page_count);
    let pages: Vec<usize> = (start..end).collect();
    editor.extract_pages(&pages, &format!("chunk_{}.pdf", start / chunk_size + 1))?;
}

Split to In-Memory Bytes (No Temp Files)

When the split chunks are headed straight to S3, an HTTP response, or another in-process step, skip the disk entirely with extract_pages_to_bytes. It returns the new PDF as bytes and leaves the source document unmodified.

Python

from pdf_oxide import PdfDocument

doc = PdfDocument("large.pdf")
chunk_size = 10
chunks = []

for start in range(0, doc.page_count(), chunk_size):
    end = min(start + chunk_size, doc.page_count())
    pages = list(range(start, end))
    chunk_bytes = doc.extract_pages_to_bytes(pages)  # bytes, not a file
    chunks.append(chunk_bytes)

print(f"Produced {len(chunks)} in-memory chunks")

Rust

let mut editor = DocumentEditor::open("large.pdf")?;
let page_count = editor.page_count()?;
let chunk_size = 10;
let mut chunks: Vec<Vec<u8>> = Vec::new();

for start in (0..page_count).step_by(chunk_size) {
    let end = (start + chunk_size).min(page_count);
    let pages: Vec<usize> = (start..end).collect();
    chunks.push(editor.extract_pages_to_bytes(&pages)?); // Vec<u8>, no file written
}

Swift

let editor = try DocumentEditor(path: "large.pdf")
let pageCount = try editor.pageCount()
let chunkSize = 10
var chunks: [[UInt8]] = []

for start in stride(from: 0, to: pageCount, by: chunkSize) {
    let end = min(start + chunkSize, pageCount)
    chunks.append(try editor.extractPagesToBytes(Array(start..<end)))
}

C++

auto editor = pdf_oxide::DocumentEditor::open("large.pdf");
int page_count = editor.page_count();
const int chunk_size = 10;
std::vector<std::vector<std::uint8_t>> chunks;

for (int start = 0; start < page_count; start += chunk_size) {
    int end = std::min(start + chunk_size, page_count);
    std::vector<int32_t> pages;
    for (int i = start; i < end; ++i) pages.push_back(i);
    chunks.push_back(editor.extract_pages_to_bytes(pages)); // bytes, no file written
}

Dart

final editor = DocumentEditor.open('large.pdf');
final pageCount = editor.pageCount;
const chunkSize = 10;
final chunks = <Uint8List>[];

for (var start = 0; start < pageCount; start += chunkSize) {
  final end = (start + chunkSize).clamp(0, pageCount);
  final pages = [for (var i = start; i < end; i++) i];
  chunks.add(editor.extractPagesToBytes(pages)); // bytes, no file written
}

R

editor <- pdf_editor_open("large.pdf")
page_count <- pdf_editor_page_count(editor)
chunk_size <- 10
chunks <- list()

for (start in seq(0, page_count - 1, by = chunk_size)) {
  end <- min(start + chunk_size, page_count)
  pages <- seq(start, end - 1)
  chunks[[length(chunks) + 1]] <- pdf_editor_extract_pages_to_bytes(editor, pages)
}

Julia

editor = open_editor("large.pdf")
n = page_count(editor)
chunk_size = 10
chunks = Vector{Vector{UInt8}}()

for start in 0:chunk_size:(n - 1)
    stop = min(start + chunk_size, n)
    pages = collect(start:(stop - 1))
    push!(chunks, extract_pages_to_bytes(editor, pages))  # bytes, no file written
end

Zig

const a = std.heap.page_allocator;
var editor = try pdf_oxide.DocumentEditor.openEditor("large.pdf");
defer editor.deinit();
const page_count = try editor.pageCount();
const chunk_size: i32 = 10;

var start: i32 = 0;
while (start < page_count) : (start += chunk_size) {
    const end = @min(start + chunk_size, page_count);
    var pages = std.ArrayList(i32).init(a);
    defer pages.deinit();
    var i = start;
    while (i < end) : (i += 1) try pages.append(i);
    const chunk = try editor.extractPagesToBytes(a, pages.items); // bytes, no file written
    a.free(chunk);
}

Objective-C

POXDocumentEditor *editor = [POXDocumentEditor openEditor:@"large.pdf" error:&err];
NSInteger pageCount = [editor pageCountError:&err];
NSInteger chunkSize = 10;
NSMutableArray<NSData*> *chunks = [NSMutableArray array];

for (NSInteger start = 0; start < pageCount; start += chunkSize) {
    NSInteger end = MIN(start + chunkSize, pageCount);
    NSMutableArray<NSNumber*> *pages = [NSMutableArray array];
    for (NSInteger i = start; i < end; i++) [pages addObject:@(i)];
    [chunks addObject:[editor extractPagesToBytes:pages error:&err]]; // bytes, no file written
}

Elixir

{:ok, editor} = PdfOxide.open_editor("large.pdf")
{:ok, n} = PdfOxide.editor_page_count(editor)
chunk_size = 10

chunks =
  0..(n - 1)
  |> Enum.take_every(chunk_size)
  |> Enum.map(fn start ->
    stop = min(start + chunk_size, n)
    {:ok, bytes} = PdfOxide.extract_pages_to_bytes(editor, Enum.to_list(start..(stop - 1)))
    bytes
  end)

extract_pages_to_bytes is available in Python, Rust, Swift, C++, Dart, R, Julia, Zig, Objective-C, Elixir, and the C ABI. It is not exposed in the WASM build.

Split by Bookmarks

For documents with an outline (table of contents), you can plan a split at bookmark boundaries — for example, one PDF per top-level chapter — without computing page ranges yourself. plan_split_by_bookmarks is the dry-run planner: it returns the segment plan (page ranges, titles, filesystem-safe file stems) without producing any PDF bytes, so you can preview, filter, or re-target the output before writing anything.

Plan the Split (Dry Run)

Python

import pdf_oxide

with open("manual.pdf", "rb") as f:
    src = f.read()

# level=1 -> split at top-level bookmarks only (0 = every depth, n = up to depth n)
segments = pdf_oxide.plan_split_by_bookmarks(src, level=1)

for seg in segments:
    # keys: index, start_page, end_page, title, file_stem, page_label
    print(f"#{seg['index']}: pages {seg['start_page']}-{seg['end_page'] - 1} "
          f"=> {seg['file_stem']}.pdf  ({seg['title']})")

Rust

use pdf_oxide::PdfDocument;
use pdf_oxide::split_bookmarks::{plan_split_by_bookmarks, SplitByBookmarksOptions, BookmarkLevel};

let doc = PdfDocument::open("manual.pdf")?;

let opts = SplitByBookmarksOptions {
    level: BookmarkLevel::TopLevel,  // top-level bookmarks only
    ..Default::default()
};

// Cheap: returns Vec<BookmarkSegment>, no PDF bytes produced
let segments = plan_split_by_bookmarks(&doc, &opts)?;
for seg in &segments {
    println!("#{}: pages {}..{} => {}.pdf ({:?})",
        seg.index, seg.start_page, seg.end_page, seg.file_stem, seg.title);
}

Swift

import PdfOxide

let doc = try PdfDocument(path: "manual.pdf")

// Returns a JSON array of segment objects (index, startPage, endPage, ...)
let planJson = try doc.planSplitByBookmarks(optionsJson: #"{"level": 1}"#)
print(planJson)

WASM

import { planSplitByBookmarks } from "pdf-oxide-wasm";

// level 1 = top-level bookmarks; returns an array of segment objects
const segments = planSplitByBookmarks(bytes, null, false, 1, true);
for (const seg of segments) {
  console.log(`#${seg.index}: ${seg.startPage}-${seg.endPage} => ${seg.fileStem}.pdf`);
}

Java

import fyi.oxide.pdf.Pdf;
import java.nio.file.*;

byte[] src = Files.readAllBytes(Path.of("manual.pdf"));

// level 1 = top-level bookmarks; returns the number of segments the split would produce
int segmentCount = Pdf.planSplitByBookmarksCount(src, 1);
System.out.println(segmentCount + " segments");

Ruby

require 'pdf_oxide'

src = File.binread('manual.pdf')

# level 1 = top-level bookmarks; returns the number of segments the split would produce
segment_count = PdfOxide::Pdf.plan_split_by_bookmarks_count(src, 1)
puts "#{segment_count} segments"

C++

auto doc = pdf_oxide::Document::open("manual.pdf");

// Returns a JSON array of segment objects (index, start_page, end_page, ...)
std::string planJson = doc.plan_split_by_bookmarks(R"({"level": 1})");
std::cout << planJson << "\n";

Dart

final doc = PdfDocument.open('manual.pdf');

// Returns a JSON array of segment objects (index, startPage, endPage, ...)
final planJson = doc.planSplitByBookmarks('{"level": 1}');
print(planJson);

R

doc <- pdf_open("manual.pdf")

# Returns a JSON array of segment objects (index, start_page, end_page, ...)
plan_json <- pdf_plan_split_by_bookmarks(doc, '{"level": 1}')
cat(plan_json, "\n")

Julia

doc = open_document("manual.pdf")

# Returns a JSON array of segment objects (index, start_page, end_page, ...)
plan_json = plan_split_by_bookmarks(doc, """{"level": 1}""")
println(plan_json)

Zig

const a = std.heap.page_allocator;
var doc = try pdf_oxide.Document.open("manual.pdf");
defer doc.deinit();

// Returns a JSON array of segment objects (index, start_page, end_page, ...)
const plan_json = try doc.planSplitByBookmarks(a, "{\"level\": 1}");
defer a.free(plan_json);
std.debug.print("{s}\n", .{plan_json});

Objective-C

POXDocument *doc = [POXDocument openPath:@"manual.pdf" error:&err];

// Returns a JSON array of segment objects (index, start_page, end_page, ...)
NSString *planJson = [doc planSplitByBookmarks:@"{\"level\": 1}" error:&err];
NSLog(@"%@", planJson);

Elixir

{:ok, doc} = PdfOxide.open("manual.pdf")

# Returns a JSON array of segment objects (index, start_page, end_page, ...)
{:ok, plan_json} = PdfOxide.plan_split_by_bookmarks(doc, ~s({"level": 1}))
IO.puts(plan_json)

Each segment carries: index (1-based ordinal), start_page (inclusive, 0-based), end_page (exclusive, 0-based — the range is start_page..end_page), title (the source bookmark title, null for a leading front-matter segment), file_stem (de-duplicated, filesystem-safe stem with no extension), and page_label.

Split Options

Option	Default	Description
title_prefix	none	Only split at bookmarks whose title starts with this prefix
ignore_case	false	Case-insensitive prefix match
level	1 (top-level)	0 = all depths, 1 = top-level only, n = up to depth n
include_front_matter	true	Emit the pages before the first split point as a leading segment

Plan, Then Extract

Because the plan is just page ranges, you can feed each segment straight into the in-memory extractor — no need to recompute boundaries.

import pdf_oxide
from pdf_oxide import PdfDocument

with open("manual.pdf", "rb") as f:
    src = f.read()

doc = PdfDocument.from_bytes(src)
for seg in pdf_oxide.plan_split_by_bookmarks(src, level=1):
    pages = list(range(seg["start_page"], seg["end_page"]))
    chunk = doc.extract_pages_to_bytes(pages)
    with open(f"{seg['file_stem']}.pdf", "wb") as out:
        out.write(chunk)

Binding coverage. plan_split_by_bookmarks is exposed in Python (module-level function pdf_oxide.plan_split_by_bookmarks), Rust (pdf_oxide::split_bookmarks::plan_split_by_bookmarks), Swift (planSplitByBookmarks), WASM (planSplitByBookmarks), and the C ABI (pdf_document_plan_split_by_bookmarks). It raises an error (Python RuntimeError) when the document has no outline — use a plain per-page or chunk split in that case.

FAQ

What is the difference between extract_pages and extract_pages_to_bytes? extract_pages(pages, output) writes the result to a file path; extract_pages_to_bytes(pages) returns the new PDF as bytes in memory. Both take 0-based page indices and leave the source document unmodified — pick the in-memory variant when the output is streamed or stored without touching disk.

Does plan_split_by_bookmarks create any PDF files? No. It is a pure, cheap planner that returns segment metadata (page ranges, titles, file stems) only. Pair it with extract_pages_to_bytes to actually produce the chunks, or use the one-shot split_by_bookmarks helper (Python/Rust/WASM) that returns segment-plus-bytes pairs.

How do I split one PDF per chapter? If your PDF has an outline, call plan_split_by_bookmarks(src, level=1) to get one segment per top-level bookmark, then extract each segment’s start_page..end_page range with extract_pages_to_bytes. Set level=0 to split at every outline depth.

Why is the split so fast? Splitting operates at the PDF object level on PDF Oxide’s pure-Rust core — the same engine that benchmarks at 0.8 ms mean extraction with a 100% pass rate. Planning a split touches only the outline and page count, so it is effectively instantaneous even on large documents.

Related Pages

• Page Operations — rotation, cropping, and reordering
• Batch Processing — parallel processing patterns
• Getting Started with Python — installation and basics