epstein-files-downloader 1.0.2

A tool to download PDFs from the DOJ Epstein files

Epstein Files Downloader

A tool to download PDF documents from the DOJ Epstein files.

🚀 Quick Start: Try it live or deploy your own — No server required, 100% client-side, completely free!

Features

Feature	CLI Tool	Web Interface
🔐 Automatic authentication	✅	✅ (via browser)
📄 Smart URL handling	✅	✅
🔄 Auto-retry on auth expiry	✅	N/A
📁 Preserves original extensions	✅	✅
🚀 Easy to use	CLI commands	One-click deploy
🐍 Python API	✅	N/A
🌐 Browser-based	❌	✅
💰 Hosting cost	Free	Free (Vercel)
🔒 Privacy	Local only	100% client-side

Choose Your Path

• Want it now? → Use the live site (fastest) or deploy your own
• Power user? → Use the CLI tool (most features)
• Building something? → Use the Python API

Installation (CLI)

Requirements

• Python 3.9 or higher
• Playwright (installed automatically)

Install from PyPI

pip install epstein-files-downloader

Install from source

git clone https://github.com/hackingbutlegal/epstein-files-downloader.git
cd epstein-files-downloader
pip install -e .

Or install dependencies first with requirements.txt:

git clone https://github.com/hackingbutlegal/epstein-files-downloader.git
cd epstein-files-downloader
pip install -r requirements.txt
pip install -e .

Install Playwright browsers

playwright install chromium

CLI Usage

Quick Start

1. Create a file with URLs (urls.txt):

   https://www.justice.gov/epstein/file/123456/dl
   https://www.justice.gov/epstein/file/123457/dl
   ...
   

2. Authenticate (one-time setup):

   epstein-auth
   

   A browser window will open. Click "Yes" on the age verification page, then press Enter in the terminal.

3. Download files:

   epstein-download -i urls.txt
   

CLI Reference

epstein-auth - Authentication

epstein-auth [OPTIONS]

Options:
  --auth-file PATH    Custom path for auth state file

epstein-download - Download files

epstein-download -i INPUT [OPTIONS]

Options:
  -i, --input PATH      Input file containing URLs (required)
  -o, --output PATH     Output directory (default: downloads)
  --auth-file PATH      Path to authentication state file
  --timeout INTEGER     Download timeout in ms (default: 60000)
  --no-retry            Don't retry with re-auth on failure
  -q, --quiet           Suppress progress output
  --version             Show version
  -h, --help            Show help message

CLI Examples

# Download to custom directory
epstein-download -i urls.txt -o ./my-documents

# Use custom auth file location
epstein-auth --auth-file ~/.epstein-auth.json
epstein-download -i urls.txt --auth-file ~/.epstein-auth.json

# Quiet mode (no progress output)
epstein-download -i urls.txt -q

Python API

You can also use this as a library in your Python scripts:

from epstein_downloader import Downloader, AuthManager

# Authenticate
auth = AuthManager()
auth.authenticate()

# Download files
downloader = Downloader(download_dir="./downloads")
urls = downloader.extract_urls_from_file("urls.txt")
downloaded = downloader.download(urls)

print(f"Downloaded {len(downloaded)} files")

Web Interface

The fastest way to get started! A fully client-side web interface - no server required.

🌐 Live Site: https://epstein-files-downloader.vercel.app

Quick Start (Web)

1. Click the "Deploy to Vercel" button above ☝️
2. Visit your deployed site
3. Click "Open DOJ Website" and complete age verification
4. Paste your URLs and download!

Features

• 🌐 100% Client-side - No data sent to any server
• 🔒 Privacy-focused - Your URLs and cookies stay in your browser
• 📋 3-Step Wizard - Guided age verification → paste URLs → download
• 📂 Batch Download - Download all files with one click
• 🔄 Retry Blocked - One-click retry if popup blocker interferes
• 📱 Mobile friendly - Works on all devices
• 🚫 No proxy - Your browser connects directly to DOJ
• 💰 Free forever - Zero hosting costs on Vercel's free tier

How It Works

The web interface works entirely in your browser:

1. URL Processing: JavaScript extracts URLs from your pasted text
2. Direct Downloads: Files open in new tabs using your browser's existing cookies
3. No Server: Nothing is sent to any server - everything happens locally

Why No Server?

The web interface uses a novel approach to avoid server-side proxying:

• Your browser already has the authentication cookie from visiting justice.gov
• We open PDF URLs in new tabs (window.open())
• The browser sends cookies automatically with these requests
• Downloads happen directly between your browser and DOJ servers

Benefits:

• Zero server costs
• Perfect privacy - we never see your URLs
• No CORS issues (navigation vs. XHR)
• Works with your existing browser session
• Instant deployment - just static files

Manual Deployment

Don't want to use the button? Deploy manually:

# Install Vercel CLI
npm i -g vercel

# Clone and deploy
git clone https://github.com/hackingbutlegal/epstein-files-downloader.git
cd epstein-files-downloader
vercel

Local Web Development

cd web
npm install
npm start

The web app will be available at http://localhost:3000.

Using the Web Interface

1. Step 1: Age Verification

   • Click "🌐 Open DOJ Website" - a new tab opens
   • Click "Yes" on the DOJ age verification page
   • Return to the app and click "✅ I've Clicked 'Yes'"

2. Step 2: Paste URLs

   • Paste text containing DOJ file URLs
   • Click "🔍 Find Files" to extract URLs

3. Step 3: Download

   • Click "⬇️ Download All" or individual "Download" buttons
   • Files open in new tabs and download automatically
   • If blocked by popup blocker, allow popups and click "🔄 Retry Blocked"

How It Works

CLI Tool

1. Authentication: The tool uses Playwright to open a real browser for age verification. Once you click "Yes", the authenticated session (cookies) is saved to a file.

2. URL Processing: The DOJ website serves files at /file/{id}/dl URLs. The tool automatically converts these to the PDF endpoint and preserves the original file extension.

3. Downloading: Files are downloaded using the authenticated session. If authentication expires during a long download session, the tool automatically re-authenticates and continues.

Web Interface

1. Client-side processing: JavaScript extracts URLs from your pasted text using regex
2. Browser authentication: Uses your existing browser cookies from visiting justice.gov
3. Direct downloads: Opens PDF URLs in new tabs, letting the browser handle authentication and download natively

Troubleshooting

CLI: "No auth file found"

Run epstein-auth first to authenticate.

CLI: "HTTP 403" errors

Your session may have expired. The tool should auto-retry, but you can also run epstein-auth again to refresh.

CLI: Playwright not found

Install Playwright browsers:

playwright install chromium

Web: Downloads not working

1. Make sure you visited DOJ first: Open https://www.justice.gov/epstein and click "Yes" on age verification
2. Same browser: Use the same browser for both the DOJ site and the web app
3. Allow popups: The web app needs to open new tabs for downloads
4. Check cookies: Some browsers block third-party cookies which may affect this

Web: Popups blocked

If you see "Popup blocked" errors:

• Look for the popup blocker icon in your address bar
• Click it and allow popups for the site
• Or change your browser settings to allow popups

Development

# Clone the repo
git clone https://github.com/hackingbutlegal/epstein-files-downloader.git
cd epstein-files-downloader

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check .
mypy src/

License

MIT License - see LICENSE file.

Disclaimer

This tool is for educational and research purposes. Please respect the DOJ website's terms of service and rate limits. The authors are not responsible for any misuse of this tool.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request