How to Configure a Password for Encrypted PDFs in opendataloader-pdf

Use the --password or -p CLI flag, or pass the password parameter to the convert() function to decrypt PDFs during extraction; the value flows from options.json through auto-generated Python bindings to the Java PDFBox engine without persistent storage.

The opendataloader-project/opendataloader-pdf repository enables extraction from password-protected documents by accepting decryption credentials at runtime. Configuring the password for encrypted PDFs requires understanding both the user-facing interfaces and the underlying data flow through the Python-to-Java bridge.

Configuring Passwords via Command Line

The simplest method uses the CLI interface defined in [options.json](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/options.json). This file declares the password flag as a string option with name: "password" and shortName: "p", serving as the single source of truth for all CLI arguments.

To extract from an encrypted PDF:

opendataloader-pdf encrypted.pdf -p mySecretPassword -o ./output

When you invoke the command, the auto-generated [convert_generated.py](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/python/opendataloader-pdf/src/opendataloader_pdf/convert_generated.py) reads the flag and appends ["--password", password] to the argument list passed to the Java JAR.

Configuring Passwords via Python API

For programmatic workflows, pass the password directly to the conversion functions.

Using the convert() Function (Recommended)

The convert() function in convert_generated.py forwards the password parameter to the Java extractor:

from opendataloader_pdf import convert

convert(
    input_path="encrypted.pdf",
    output_dir="./output",
    password="mySecretPassword",
    format=["json", "markdown"]
)

Using the Deprecated run() Wrapper

Backward compatibility is maintained through [wrapper.py](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/python/opendataloader-pdf/src/opendataloader_pdf/wrapper.py), though this approach will be removed in future releases:

from opendataloader_pdf import run

run(
    input_path="encrypted.pdf",
    output_folder="./output",
    password="mySecretPassword"
)

Architecture: How Passwords Flow to the Java Engine

Understanding the internal pipeline demonstrates why the configuration works consistently across interfaces. The password travels through three distinct layers before decryption occurs, generated by running npm run generate-options:

1. Options Definition: [options.json](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/options.json) centrally defines the --password flag and its short form -p.

2. CLI Binding Generation: The auto-generated [convert_generated.py](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/python/opendataloader-pdf/src/opendataloader_pdf/convert_generated.py) builds the argument list including ["--password", password] when the parameter is present.

3. Java Extraction Core: The JAR receives the flag and routes it to [PDFWriter.java](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/java/opendataloader-pdf-core/src/main/java/org/opendataloader/pdf/pdf/PDFWriter.java), where PDFBox's Loader.loadPDF(File, String) method opens the encrypted document.

This architecture ensures the password is treated as a transient string argument rather than a persistent configuration value.

Security and Data Handling

The opendataloader-pdf implementation treats passwords as ephemeral runtime data. Because the value exists only in memory during the extraction process and is never written to disk or stored in configuration files, the risk of credential leakage through logs or cached state is minimized. The password exists solely within the process memory from the CLI invocation through the Python binding until PDFBox consumes it in the Java virtual machine.

Summary

• Use --password or -p flags for CLI extractions from encrypted PDFs
• Pass the password parameter to convert() for programmatic access
• The deprecated run() wrapper in wrapper.py still accepts passwords but should be avoided
• Passwords flow from options.json through convert_generated.py to PDFWriter.java and PDFBox
• Credentials remain transient in memory and are never persisted to storage

Frequently Asked Questions

What is the short flag for the password option?

The short flag is -p, while the long form is --password. Both are defined in the project's options.json file and processed identically by the auto-generated CLI parser in convert_generated.py.

Does opendataloader-pdf store my password after extraction?

No. According to the source code implementation in convert_generated.py and PDFWriter.java, the password is treated as a normal string argument that exists only in memory during the extraction process. It is never written to configuration files, logs, or persistent storage.

Which Python function should I use to provide a password programmatically?

Use the convert() function located in convert_generated.py. While the deprecated run() wrapper in wrapper.py still accepts a password parameter, the project maintainers recommend migrating to convert() as the run() function will be removed in future releases.

How does the password reach the Java PDFBox engine?

The password flows through a three-layer pipeline: first defined in options.json, then passed through the auto-generated Python bindings in convert_generated.py, and finally consumed by PDFWriter.java which calls PDFBox's Loader.loadPDF(File, String) method to decrypt the document.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}