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

> Securely extract data from encrypted PDFs using opendataloader-pdf. Configure your password via CLI flag or Python parameter for seamless decryption and data access.

- Repository: [opendataloader-project/opendataloader-pdf](https://github.com/opendataloader-project/opendataloader-pdf)
- Tags: how-to-guide
- Published: 2026-03-20

---

**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`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/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)](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:

```bash
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/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`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/convert_generated.py) forwards the password parameter to the Java extractor:

```python
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/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:

```python
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)](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/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/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`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/wrapper.py) still accepts passwords but should be avoided
- Passwords flow from [`options.json`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/options.json) through [`convert_generated.py`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/convert_generated.py) to [`PDFWriter.java`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/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`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/options.json) file and processed identically by the auto-generated CLI parser in [`convert_generated.py`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/convert_generated.py).

### Does opendataloader-pdf store my password after extraction?

No. According to the source code implementation in [`convert_generated.py`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/convert_generated.py) and [`PDFWriter.java`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/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`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/convert_generated.py). While the deprecated `run()` wrapper in [`wrapper.py`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/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`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/options.json), then passed through the auto-generated Python bindings in [`convert_generated.py`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/convert_generated.py), and finally consumed by [`PDFWriter.java`](https://github.com/opendataloader-project/opendataloader-pdf/blob/main/PDFWriter.java) which calls PDFBox's `Loader.loadPDF(File, String)` method to decrypt the document.