API Installation

Use pdfcpu as a Go library. v0.16 requires Go 1.26.0 or later.

Install

go get github.com/pdfcpu/pdfcpu@latest

The examples below use the v0.16 API.

Usage

Import the API package:

import "github.com/pdfcpu/pdfcpu/pkg/api"

The example below uses api.ValidateFile:

func ValidateFile(c context.Context, inFile string, conf *model.Configuration, options *ProgressOptions) error

model.Configuration is defined in github.com/pdfcpu/pdfcpu/pkg/pdfcpu/model.

ProgressOptions belongs to package api, so callers refer to it as api.ProgressOptions. The function returns nil on success or an error if validation fails or the operation is canceled.

Example:

package main

import (
    "context"
    "log"

    "github.com/pdfcpu/pdfcpu/pkg/api"
)

func main() {
    if err := api.ValidateFile(context.Background(), "input.pdf", nil, nil); err != nil {
        log.Fatal(err)
    }
}

Context and cancellation

Long-running pdfcpu operations take a Go context as their first argument. Pass context.Background() when no cancellation is needed, as in the example above. In a server or job runner, pass the request or job context instead. Canceling it asks pdfcpu to stop and return an error. For file-producing operations, cancellation before final replacement preserves an existing destination.

Do not pass a nil context.

Configuration

Pass nil to load the default configuration; this may initialize files on disk.
Load an explicit configuration to control its mode, settings, fonts or trusted certificates.

For execution without filesystem state, use:
api.LoadConfiguration(api.ConfigurationOptions{Mode: api.ConfigurationModeStateless})
and pass the returned configuration.

A configuration supplied by your application remains yours and can be reused after an operation. Clone it before applying different settings for another job; do not mutate it while concurrent operations use it.

See Configuration Modes for loading options and Configuration Reset Required in v0.16 when upgrading an existing application.

Upgrading to v0.16

Long-running operations now use their regular API names with a required context. Validation and optimization operations also accept an optional progress argument; pass nil when progress events are not needed.

The v0.16 upgrade guide contains the configuration and progress examples.

Documentation

• API: pkg.go.dev docs
• Examples:
  • API tests
  • Sample files