pdfunlock-cli 1.0.0

Remove password protection from PDF files you own, given the correct password.

pdfunlock

A small command-line tool that removes password protection from PDF files you own, when you supply the correct password.

What it is not: pdfunlock does not crack, guess, brute-force, or bypass passwords. If you don't know the password, this tool cannot (and will not) help.

Installation

pip install pdfunlock-cli

Or with pipx for an isolated install:

pipx install pdfunlock-cli

Either way you get the pdfunlock command and the pdfunlock Python module.

Requires Python 3.10 or newer.

Usage

pdfunlock PDF_FILE [OPTIONS]

Options:
  -o, --output PATH    Output path for the decrypted PDF.
                       Defaults to <name>_unlocked.pdf next to the input.
  -p, --password TEXT  Password for the PDF. If omitted, you are prompted
                       securely (input is never echoed).
  --in-place           Overwrite the original file instead of writing a copy.
  -V, --version        Show the version and exit.
  --help               Show this message and exit.

Examples

Decrypt a PDF, prompting securely for the password:

$ pdfunlock protected.pdf
Password for protected.pdf:
Success: decrypted PDF saved to 'protected_unlocked.pdf'.

Choose where the decrypted copy is written:

$ pdfunlock protected.pdf --output unlocked.pdf
Password for protected.pdf:
Success: decrypted PDF saved to 'unlocked.pdf'.

Pass the password on the command line (note: visible in shell history — prefer the prompt):

$ pdfunlock protected.pdf --password mypassword
Success: decrypted PDF saved to 'protected_unlocked.pdf'.

Overwrite the original file:

$ pdfunlock protected.pdf --in-place
Password for protected.pdf:
Success: decrypted PDF saved to 'protected.pdf'.

Wrong password? You get a clear error and a non-zero exit code:

$ pdfunlock protected.pdf --password oops
Incorrect password for 'protected.pdf'.

Already-unprotected files are handled gracefully too:

$ pdfunlock plain.pdf --password anything
'plain.pdf' is not password-protected. Nothing to do.

Python API

The same functionality is available as a library:

from pdfunlock import unlock_pdf, InvalidPasswordError

try:
    out = unlock_pdf("protected.pdf", "mypassword")
    print(f"Saved to {out}")
except InvalidPasswordError:
    print("Wrong password")

Development

git clone https://github.com/akurathisasidhar/pdfunlock
cd pdfunlock

# Create a virtual environment
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # macOS / Linux

# Editable install with dev tools
pip install -e ".[dev]"

# Run the test suite
pytest

# With coverage
pytest --cov=pdfunlock

Project layout:

pdfunlock/
├── pyproject.toml
├── LICENSE
├── README.md
├── src/
│   └── pdfunlock/
│       ├── __init__.py     # public API + version
│       ├── cli.py          # Typer CLI entry point
│       ├── core.py         # decryption logic
│       ├── exceptions.py   # error types
│       └── py.typed        # PEP 561 marker
└── tests/
    ├── conftest.py         # generates test PDFs on the fly
    ├── test_core.py
    └── test_cli.py

Publishing

Build the source distribution and wheel:

python -m build

Test the wheel locally before uploading:

pip install dist/pdfunlock_cli-1.0.0-py3-none-any.whl
pdfunlock --version

Upload to TestPyPI first (recommended):

twine upload --repository testpypi dist/*
pip install --index-url https://test.pypi.org/simple/ pdfunlock-cli

Then publish to PyPI:

twine upload dist/*

To release a new version: bump __version__ in src/pdfunlock/__init__.py, rebuild, and re-upload.

License

MIT