safaribooks

Download O'Reilly books as EPUB files. Async. Cookie-based auth that actually works.

Note

For personal and educational use only. Please read O'Reilly's Terms of Service.

Upgrading from v1? The CLI moved from python3 safaribooks.py <ID> to safari fetch <ID>. Run safari --help for the new commands. The old scripts remain as _safaribooks_legacy.py for reference only.

$ safari auth setup
Paste cookies (JSON, header, or extension export):
{"groot_sessionid":"abc...","logged_in":"y","jwt":"eyJ...","csrf_access_token":"tok_..."}
Cookies saved to ~/.config/safaribooks/cookies.json (4 cookies)

$ safari fetch 9781491958698
Downloading 1 book(s)...

──── Book 1/1: 9781491958698 ────
  Fetching book info...        ━━━━━━━━━━━━━━━━━━━━ 100%  0:00:01
  Downloading chapters (53)... ━━━━━━━━━━━━━━━━━━━━ 100%  0:00:12
  Downloading CSS (2 files)... ━━━━━━━━━━━━━━━━━━━━ 100%  0:00:01
  Downloading images (142)...  ━━━━━━━━━━━━━━━━━━━━ 100%  0:00:08
  Building EPUB...             ━━━━━━━━━━━━━━━━━━━━ 100%  0:00:01
Saved: Books/Test-Driven Development with Python 2nd Edition.epub

──── Summary ────
Downloaded: 1 book(s)

Install

uv tool install safaribookshelf

pip install safaribookshelf

docker build . -t safaribooks

# Extract cookies on host first:
safari auth setup

# Run:
docker run --rm \
    -e SAFARI_COOKIES_FILE=/app/cookies.json \
    -v $(pwd)/cookies.json:/app/cookies.json \
    -v $(pwd)/Books:/app/Books \
    safaribooks 9781491958698

Quick Start

1. Set up authentication -- paste cookies from your browser:

   safari auth setup
   

2. Download a book by ID:

   safari fetch 9781491958698
   

3. Download an entire playlist:

   safari fetch --playlist 6f612b99-bebc-41e1-8fff-6b655507b7af
   

4. Search by title:

   safari fetch "Python Cookbook"
   

Why This Exists

O'Reilly killed programmatic login years ago, and the v1 API that the original safaribooks tool relied on was eventually shut down. The upstream repo is unmaintained and no longer functional.

This fork synthesized 20+ community PRs into a modern async rewrite: httpx instead of requests, tenacity for retries, a token-bucket rate limiter, Pydantic v2 config, and a proper typer CLI. It migrated the entire API surface from v1 to v2 and unified cookie authentication into a single workflow.

See the archived contributors page for full credit.

CLI Reference

Commands

Fetch Options

Authentication Methods

O'Reilly blocks programmatic login. You need cookies from an active browser session.

Step 1: Log in at https://learning.oreilly.com in your browser.

Step 2: Get cookies via one of these methods:

Method 1: Auto-Extract from Browser (Recommended)

pip install browser_cookie3
safari auth extract --browser chrome

Also supports: firefox, edge, chromium.

Auto-refresh: Set SAFARI_AUTO_REFRESH_BROWSER=chrome (or your browser) to automatically re-extract cookies when they expire mid-download — no manual intervention needed.

Method 2: Interactive Paste

safari auth setup

Auto-detects JSON dict, browser extension export, or raw cookie header. Get JSON from your browser console:

JSON.stringify(
  document.cookie.split(";").reduce((o, c) => {
    c = c.trim();
    let i = c.indexOf("=");
    o[c.substring(0, i)] = c.substring(i + 1);
    return o;
  }, {}),
);

Method 3: Raw Cookie Header

safari auth import --header 'Cookie: k1=v1; k2=v2; ...'

Method 4: Browser Extension Export

safari auth import --file exported_cookies.json

Method 5: Manual JSON

Create ~/.config/safaribooks/cookies.json:

{
  "groot_sessionid": "...",
  "logged_in": "y",
  "jwt": "...",
  "csrf_access_token": "..."
}

Required cookies: groot_sessionid, jwt, csrf_access_token, logged_in.

Validate: safari auth validate

Troubleshooting

Security warning: cookies.json contains your active session -- treat it like a password. It's in .gitignore.

Configuration

All settings can be set via environment variables with the SAFARI_ prefix (powered by pydantic-settings):

Architecture

flowchart TD
    CLI["CLI (Typer)"] --> BD["BookDownloader"]
    BD --> Auth["check_login()"]
    BD --> Meta["fetch_book_info()"]
    Meta --> Enrich["enrich_metadata()"]
    BD --> Chapters["fetch_chapters()"]
    Chapters --> Process["process_chapters()"]
    Process --> CSS["download_css()"]
    CSS --> Fonts["download_fonts()"]
    Fonts --> Images["download_images()"]
    Images --> Videos["download_videos()"]
    Videos --> EPUB["build_epub()"]
    BD -.-> API["ApiClient (httpx)"]
    API --> RL["TokenBucketRateLimiter"]
    API --> Retry["RetryConfig (tenacity)"]

Docker Usage

The Docker image uses uv and runs safari fetch as the entrypoint:

# Build the image
docker build . -t safaribooks

# Extract cookies on host first
safari auth setup

# Run a download
docker run --rm \
    -e SAFARI_COOKIES_FILE=/app/cookies.json \
    -v $(pwd)/cookies.json:/app/cookies.json \
    -v $(pwd)/Books:/app/Books \
    safaribooks 9781491958698

To pass additional flags, append them after the book ID:

docker run --rm \
    -e SAFARI_COOKIES_FILE=/app/cookies.json \
    -v $(pwd)/cookies.json:/app/cookies.json \
    -v $(pwd)/Books:/app/Books \
    safaribooks 9781491958698 --kindle --rate-limit 0.5

Calibre / E-Reader Tips

The EPUB generated by safari fetch is functional but contains raw HTML/CSS from O'Reilly. For the best reading experience, convert it with Calibre:

ebook-convert \
    "Books/Test-Driven Development with Python 2nd Edition.epub" \
    "Books/Test-Driven Development with Python 2nd Edition_clean.epub"

For Kindle users:

• Use safari fetch --kindle 9781491958698 to add CSS rules that prevent table and code block overflow on e-ink screens.
• Convert to AZW3 or MOBI with Calibre. When converting, select Ignore margins in the conversion options for best results.

Contributing

uv sync              # install deps
just check           # lint + format + type check
just test            # run tests

See CONTRIBUTING.md for the full guide.

Credits

Originally created by Lorenzo Di Fuccia. This fork synthesized 20+ community contributions -- see full credits.