English | Bahasa Indonesia

✨ About

WattPDL is a lightweight Python script that downloads the chapters of a Wattpad story of your choice and saves them as a clean, tidy plain .txt file, a Word .docx document, an .epub ebook, a Markdown .md file, or a .pdf. You can download the whole story as a single file, every chapter separately in one .zip, or only the chapters you pick, complete with the story cover automatically embedded in .docx/.epub/.pdf. No login, no API key, just the story link or ID.

"Because a good story deserves to be read anytime, even without internet."

🎯 Features

📦 Requirements

• Python 3.9 or newer
• Internet connection
• Libraries: requests, rich, python-docx, EbookLib, reportlab, installed automatically together with wattpdl, no manual install needed

Never used a terminal? Start here

Don't have Python yet?

1. Go to python.org/downloads and download the latest version
2. Windows only: during installation, tick the "Add Python to PATH" box on the first screen before clicking Install. If you miss this, the python command will not be recognized later
3. After installing, open a terminal (see the guide above) and check with:

python --version
# or
python3 --version

If a version number appears (for example Python 3.12.1), you are ready.

🚀 Installation

Option A: Install from PyPI (easiest)

pip install wattpdl

If pip is not recognized, try:

python -m pip install wattpdl

If you get an externally-managed-environment error (usually on Linux):

pip install wattpdl --break-system-packages

Once installed, the wattpdl command works from any terminal. Continue to Usage.

Option B: Install from source (for development / to read or change the code)

1. Get the project code

git clone https://github.com/nekonaru/wattpdl.git
cd wattpdl

cd Downloads/wattpdl-main

2. Install in "editable" mode

pip install -e .

Same as Option A, add --break-system-packages at the end if you get an externally-managed-environment error.

This also registers the wattpdl command, but it loads the code directly from this folder, which is ideal if you want to modify the code and see the result right away without reinstalling.

🖥️ Usage

Run:

wattpdl

If you installed from source without pip install -e ., run it with python -m wattpdl from inside the src/ folder. The editable install above is recommended, though.

Enter the story link or ID when asked:

Wattpad story link or ID: https://www.wattpad.com/story/123456789-story-title

or just the ID:

Wattpad story link or ID: 123456789

Choose the download mode:

  1  All chapters → 1 combined file
  2  All chapters → separate file per chapter, packed as .zip
  3  Select several chapters → 1 combined file
  4  Select 1 chapter only

Select mode [1/2/3/4] (1):

• Mode 1: the most common way, the whole story as one tidy file from the first to the last chapter
• Mode 2: good if you want to read chapter by chapter, producing one .zip with a file per chapter
• Mode 3: a numbered list of all chapter titles appears, then type the numbers you want, combining commas and ranges, for example: 1,3,5-8
• Mode 4: a list of all chapter titles appears, type a single number to download only that chapter

Choose the file format:

  1  Plain text (.txt)
  2  Word document (.docx)
  3  Ebook (.epub)
  4  Markdown (.md)
  5  PDF (.pdf)

Select file format [1/2/3/4/5] (1):

Choose the save folder:

Default folder: C:\Users\user\Downloads
Press Enter to use that folder, or type another path:

Press Enter to save in Downloads, or type a custom path such as:

• Windows: D:\Stories\Wattpad
• Linux/macOS: /home/user/stories

Wait for it to finish:

⠋ Chapter 24...              ████████████████░░░░░░░░░░░░░░  53.3%  24/45  0:00:12  left 0:00:11

Done! 🎉

╔══════ 🎉 Success!  All chapters saved ══════╗
║ 📁 File saved to   C:\Users\user\Downloads\Story_Title.txt ║
║ ✅ Succeeded       45/45                                   ║
║ ⏱️  Total time      2m 18s                                  ║
╚═════════════════════════════════════════════╝

↻ Automatic Resume

If the download stops midway (connection lost, terminal closed, laptop shut down), every chapter that already succeeded is saved automatically in ~/.wattpdl/progress/<story_id>.json.

Run again with the same story (same ID/link), and WattPDL will:

• Skip chapters that already succeeded (used from the cache, not fetched again)
• Download only the chapters that have not succeeded yet or failed earlier

The progress file is deleted automatically once all chapters have been downloaded in a single session. To force a download from scratch, delete the ~/.wattpdl/progress/ folder manually.

Not the same as --skip-existing: the resume above works at the chapter level (continuing a download that stopped midway). --skip-existing works at the output file level: if the final file (for example Story_Title.epub) already exists in the target folder, the whole download is skipped entirely, which is handy together with cron/Task Scheduler so stories that were already downloaded are not downloaded again.

⚙️ Saved Preferences

The last save folder, file format, and display language you chose are saved automatically in ~/.wattpdl/config.json and reused as defaults in the next session, so there is no need to fill them in every time you run the script.

🌍 Display Language

The CLI display (menus, prompts, error messages, and --help text) is available in English (default) and Indonesian.

wattpdl --ui-lang id              # Indonesian, this choice is remembered for next runs
wattpdl --ui-lang en              # back to English
WATTPDL_LANG=id wattpdl           # via environment variable

Priority order: --ui-lang → env WATTPDL_LANG → ui_lang in ~/.wattpdl/config.json → default en.

--ui-lang only changes the CLI display. Do not confuse it with --lang, which sets the language code in the EPUB metadata.

🤖 Non-Interactive Mode (Scripting/Automation)

Besides the question-and-answer mode, WattPDL can also be run through command line arguments, which is great for scheduling (cron/Task Scheduler) or calling from other scripts.

wattpdl --id 398440633 --mode 1 --format docx

Available arguments:

More examples:

# Download all chapters as separate files in a .zip
wattpdl --id 398440633 --mode 2 --format txt

# Download only chapters 1, 3, and 5-8 as 1 combined file
wattpdl --id 398440633 --mode 3 --chapters 1,3,5-8 --format docx

# Download only chapter 10, save to a custom folder
wattpdl --id 398440633 --mode 4 --chapter 10 --output-dir "D:\Wattpad Stories"

# Download all chapters as 1 .epub ebook
wattpdl --id 398440633 --mode 1 --format epub

# Download as Markdown, skip if the file already exists (good for scheduling)
wattpdl --id 398440633 --mode 1 --format md --skip-existing

# Show all options
wattpdl --help

📂 Output Structure

The name and shape of the generated files depend on the mode & format you choose:

Content of the combined file (modes 1 & 3): the story title, author, and source at the top, then each chapter separated by a ##### marker.

Story Title
by Author Name
Source: https://www.wattpad.com/story/123456789

==================================================

##### Chapter 1 Title #####

Text of chapter 1...

##### Chapter 2 Title #####

Text of chapter 2...

In the .docx version, the story title becomes the main heading and each chapter automatically becomes a Heading 1 on a new page, so it is comfortable to read right away in Word or Google Docs.

In the .epub version, the story becomes a standard ebook with an automatic table of contents per chapter, ready to open in your favorite ebook reader (Google Play Books, Apple Books, Calibre, and others).

In the .md version, the story is written with standard Markdown headings (# for the title, ## per chapter), which is pleasant to open in any editor or render directly on GitHub/Obsidian/Notion.

If the story has a cover, the image is embedded automatically on the first page/paragraph of the .docx/.epub/.pdf file (unless run with --no-cover). The story's genre/tags, description, and publish date are also saved as official metadata in the .epub file, usually shown on the book detail page in ebook reader apps.

Zip content (mode 2): one file per chapter, numbered by its position in the story, plus 000_info.txt/000_info.md/000_info.docx/000_info.epub/000_info.pdf (matching the format) containing the title, author, and source. The file extension inside the zip follows the format you chose when running the script:

Story_Title.zip
├── 000_info.txt
├── 001_Chapter_1_Title.txt
├── 002_Chapter_2_Title.txt
└── ...

🗺️ Default Folder per OS

⚠️ Troubleshooting

📝 Important Notes

• The story ID is the number in the Wattpad URL, right after /story/
• The script uses a public endpoint, no login or API key needed
• The 0.5 second delay between chapters is set to avoid server rate limits, please do not remove it
• This script is only for reading your own stories or public stories offline. Respect the authors' copyright

🛠️ Built With

🗂️ Project Structure

wattpdl/
├── src/
│   └── wattpdl/
│       ├── __init__.py       # package metadata (__version__)
│       ├── __main__.py       # entry point for `python -m wattpdl`
│       ├── app.py            # program flow orchestration (main())
│       ├── api.py            # communication with the Wattpad public API
│       ├── writers.py        # text conversion & writing .txt/.docx/.epub/.md/.pdf/.zip files
│       ├── cli.py            # terminal display (rich), user interaction
│       ├── cli_args.py       # argument parsing for non-interactive mode
│       ├── config.py         # saves user preferences (save folder, format, language)
│       ├── i18n.py           # CLI display translations (en/id)
│       └── progress.py       # download progress cache for the resume feature
├── requirements.txt          # dependency list (for manual reference)
├── pyproject.toml            # package metadata + build config + ruff
├── tests/
│   ├── __init__.py
│   └── test_wattpdl.py       # unit tests (pytest)
├── .github/
│   └── workflows/
│       ├── tests.yml         # CI: automatic test, lint, & build check
│       └── publish.yml       # auto-publish to PyPI on a new release
├── CONTRIBUTING.md           # contribution guide (English)
├── CONTRIBUTING.id.md        # contribution guide (Indonesian)
├── LICENSE
├── README.md                 # main documentation (English)
└── README.id.md              # documentation (Indonesian)

Module separation principles:

• api.py: knows nothing about the display (rich), purely fetches data
• writers.py: makes no network requests, purely converts & writes files
• cli.py: all user interaction & progress bar display
• cli_args.py: command line argument parsing & validation, no business logic
• i18n.py: display text dictionary (English/Indonesian), pure data, knows nothing about rich or the network
• config.py / progress.py: read/write JSON files in ~/.wattpdl/, know nothing about the CLI or the network
• app.py: ties everything together, with no business logic of its own (invoked through the wattpdl command after install)

🧪 Testing

There are unit tests for the core functions (story ID parsing, file name validation, chapter selection parsing, HTML to text conversion, config, progress/resume, CLI argument parsing, translations, and more).

pip install -e .[dev]
pytest tests/ -v
ruff check .

🤝 Contributing

Want to help improve WattPDL? Read CONTRIBUTING.md for the project structure and contribution flow.

❓ FAQ

👤 Author

Nicolas Dwi Dharma
github.com/nekonaru

📄 License

Distributed under the MIT License. See LICENSE for more information.