---
name: unlock-pdfs
description: Removes passwords from PDF files. Use when the user needs to unlock password-protected PDFs, process protected documents, or prepare PDFs for submission where passwords need to be removed.
---

# Unlock PDFs

Batch removal of passwords from PDF files using passwords stored in environment variables.

## Overview

Removes password protection from PDF files while preserving content. Works with any password-protected PDF including financial documents, contracts, reports, or forms that need to be submitted or processed without protection.

**Common use cases:**
- Bank statements and financial documents
- Tax forms and accounting records
- Legal contracts requiring submission
- Reports and documents needing to be shared without restrictions

## Quick start

**Basic usage:**
```bash
python scripts/unlock_pdfs.py "Statement.pdf"
```

Creates `Statement_unlocked.pdf` in the same directory.

## Setup

### 1. Install dependencies

```bash
pip install pikepdf python-dotenv
```

### 2. Configure passwords

Create `.env` file in the project root:

```bash
# Default password (tried first)
PDF_PASSWORD=your_default_password

# Additional passwords for different document types
PDF_PASSWORD_PERSONAL=your_personal_password
PDF_PASSWORD_BUSINESS=your_business_password
```

**Tips:**
- You can configure multiple passwords for different document sources
- The script tries all configured passwords until one succeeds
- Common passwords include: ID numbers, account numbers, dates (YYYYMMDD), or custom passwords

### 3. Secure the .env file

Add to `.gitignore`:
```
.env
```

## Usage patterns

### Single file
```bash
python scripts/unlock_pdfs.py "Document.pdf"
```
Output: `Document_unlocked.pdf`

**Example with bank statement:**
```bash
python scripts/unlock_pdfs.py "Cheque Statement - 26-01-04.pdf"
```
Output: `Cheque Statement - 26-01-04_unlocked.pdf`

### Multiple files
```bash
python scripts/unlock_pdfs.py document1.pdf document2.pdf document3.pdf
```

### Batch process directory
```bash
python scripts/unlock_pdfs.py Documents/*.pdf
```

**Example with bank statements:**
```bash
python scripts/unlock_pdfs.py Banking/*.pdf
```

### Custom output directory
```bash
python scripts/unlock_pdfs.py -o unlocked_documents/ *.pdf
```

### Replace original files
```bash
python scripts/unlock_pdfs.py --in-place "Document.pdf"
```
⚠️ Use with caution - overwrites original files.

## Output indicators

- ✅ Success: PDF unlocked and saved
- ❌ Failure: Wrong password or error
- ℹ️ Info: PDF not password-protected

## Script reference

**Location**: `scripts/unlock_pdfs.py`

**Command-line options:**
- `files` (required): One or more PDF files to process
- `-o, --output-dir`: Directory for unlocked files
- `--in-place`: Replace original files (destructive)

**Environment variables:**
- `PDF_PASSWORD`: Default password
- `PDF_PASSWORD_PERSONAL`: Personal documents password
- `PDF_PASSWORD_BUSINESS`: Business documents password

## Workflow

1. **Configure**: Set passwords in `.env` file
2. **Run**: Execute script with file paths
3. **Verify**: Check for `_unlocked.pdf` files
4. **Use**: Submit or process unlocked PDFs

## Security notes

- Passwords stored in `.env` (excluded from version control)
- All processing happens locally - no external services
- Original files preserved unless `--in-place` used
- Unlocked files have standard permissions

## Troubleshooting

**"No passwords found"**
- Check `.env` file exists
- Verify environment variables are set
- Confirm `python-dotenv` is installed

**"None of the passwords worked"**
- Verify password is correct (try opening PDF manually)
- Check for extra spaces in `.env` file
- Try common password patterns: ID numbers, dates, account numbers, or contact document creator

**"File not found"**
- Check file path is correct
- Use quotes around filenames with spaces
- Verify file has `.pdf` extension