pixiv-novel-dl

High‑fidelity Pixiv novel downloader & converter (HTML / Markdown) with optional image embedding and WebP optimization.

Highlights

• 📥 Download any public Pixiv novel (authentication supported for restricted content)
• 🖼️ Image handling:
  • Embed all images directly in a single HTML file (base64)
  • Or store images separately in an images/ directory (--no-embed)
  • Optional WebP conversion for size reduction
• 📝 High-fidelity Markdown output (via Pandoc) that mirrors the HTML structure
  • Preserves title, description, images, layout breaks, ruby readings (converted)
• ⚡ Fast parallel image retrieval
• 🔍 Clean, minimal default logging (toggle --verbose for details)
• 🧩 Can be used as a TypeScript/JavaScript library
• ✅ Graceful handling of missing / restricted content (with guidance)
• 🛠️ Well-structured, publish-ready, scriptable

Install

Global (recommended for CLI)

npm install -g pixiv-novel-dl
# or
bun add -g pixiv-novel-dl

Project (library usage)

npm install pixiv-novel-dl
# or
bun add pixiv-novel-dl

Optional: Pandoc (only required for --markdown)

| Platform | Command | |----------|---------| | macOS (Homebrew) | brew install pandoc | | Debian/Ubuntu | sudo apt install pandoc | | Windows | Download installer from https://pandoc.org/installing.html |

Quick Start

pixiv-novel-dl "https://www.pixiv.net/novel/show.php?id=NNNNNNNN"

Produces:

R 女の子たちが... - pixiv - NNNNNNNN.html

Download with separate image files:

pixiv-novel-dl "https://www.pixiv.net/novel/show.php?id=NNNNNNNN" --no-embed

Generate Markdown (with external images):

pixiv-novel-dl "https://www.pixiv.net/novel/show.php?id=NNNNNNN" --no-embed --markdown

Custom output directory & filename:

pixiv-novel-dl "https://www.pixiv.net/novel/show.php?id=NNNNNNN" \
  --output ./novels \
  --filename my-favorite

CLI Usage

pixiv-novel-dl <url> [options]

Arguments:
  url                   Pixiv novel URL (https://www.pixiv.net/novel/show.php?id=NNNNNNN)

Options:
  -c, --cookies <path>  Path to cookies.txt for authenticated / R-18 content (default: cookies.txt)
  -o, --output <dir>    Output directory (default: .)
  -f, --filename <name> Custom filename (no extension)
      --no-embed        Do NOT embed images (store in ./images/)
      --convert-webp    Convert images to WebP (default: true)
      --no-convert-webp Keep original image formats
      --markdown        Also produce Markdown (requires pandoc)
  -v, --verbose         Verbose logging (network, images, sizes)
  -h, --help            Show help

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Invalid input / runtime error | | 2 | Network / fetch error | | 3 | Authentication required but not satisfied | | 4 | Pandoc conversion failure (when --markdown) |

Output Layout

Embedded (default)

R Title - pixiv - 12345678.html

All images inline as data: URIs.

Separate Images (--no-embed)

R Title - pixiv - 12345678.html
images/
  cover.webp
  tei12345.webp
  ...

With Markdown (--markdown --no-embed)

R Title - pixiv - 12345678.html
R Title - pixiv - 12345678.md
images/
  ...

High-Fidelity Markdown

The Markdown converter:

• Preserves paragraph & blank line rhythm
• Converts <ruby>漢字<rt>かんじ</rt></ruby> into: 漢字（かんじ）
• Maintains images (same relative paths or embedded data if you used embedding)
• Adds a metadata footer:

  ---
  Tags: tag1, tag2
  Original: https://www.pixiv.net/novel/show.php?id=...
  ID: 12345678
  Author: username (123456)
  Bookmarks: 270
  Date: 2025-04-19
  Downloaded with Pixiv Novel Downloader – Markdown mode

Authentication (R-18 / Restricted Novels)

Some novels require a logged-in Pixiv session.

1. Log in to Pixiv in your browser.
2. Export cookies using a browser extension:
   • Firefox: https://addons.mozilla.org/firefox/addon/cookies-txt/
   • Chrome: https://chrome.google.com/webstore/detail/get-cookiestxt/bgaddhkoddajcdgocldbbfleckgcbcid
3. Save as cookies.txt (Netscape format) in your working directory.
4. Pass explicitly if needed:

   pixiv-novel-dl "URL" --cookies ./cookies.txt

If content is missing or replaced with a warning block, you likely need valid cookies.

Library API (ESM)

import { downloadNovel } from "pixiv-novel-dl";

const result = await downloadNovel(
  "https://www.pixiv.net/novel/show.php?id=NNNNNNNN",
  {
    cookiesPath: "./cookies.txt",
    embedImages: true,
    convertToWebp: true,
    convertToMarkdown: false,
    outputDir: "./downloads",
    filename: "custom-name"
  }
);

console.log(result.title, result.filepath, result.format);

Returned Structure

interface DownloadResult {
  filepath: string;           // Final file path
  title: string;
  id: string;
  imageCount: number;
  embeddedImageSize: number;  // Bytes (when inline)
  format: "html" | "markdown";
}

Logging

| Mode | Behavior | |------|----------| | Default | Clean summary, warnings only when actionable | | --verbose | Image-by-image progress, converted sizes, debug hints |

Pandoc absence is only noted when --markdown is requested and conversion fails.

Edge Cases & Notes

| Case | Behavior | |------|----------| | Deleted/private novel | Graceful placeholder content | | Missing images | Placeholder figure with a warning label | | Huge novels | Streaming is not required; in-memory build is usually fine | | Ruby overload | Converted to readable inline parentheses | | Rate limits | May fail with HTTP errors (retry later with cookies) |

Roadmap / Ideas

• Series batch downloading
• Progress bar / ETA
• Retry with exponential backoff
• Optional EPUB output
• Configurable ruby output modes

(Open an issue if you want to influence priority.)

Contributing

1. Fork: https://github.com/thr12345/pixiv-novel-dl
2. Create a branch: feat/xyz
3. Run locally:

   bun install
   bun src/cli.ts "https://www.pixiv.net/novel/show.php?id=NNNNNNNN"

4. Add tests / examples where reasonable
5. Submit a pull request with a clear description

Troubleshooting

| Symptom | Fix | |---------|-----| | Empty body | Provide valid cookies (--cookies cookies.txt) | | Pandoc error | Install pandoc & ensure in PATH | | Garbled filename | Tool sanitizes forbidden characters automatically | | Images missing (no-embed) | Check images/ was created; verify network/cookies | | Markdown missing images | Use --no-embed if you want relative image files instead of embedded HTML-only URIs |

Run with --verbose for more context.

Legal / Ethical Notice

This tool is intended for personal archiving and offline reading of content you already have legal access to on Pixiv.

You are responsible for:

• Complying with Pixiv's Terms of Service
• Respecting creators' distribution preferences
• Avoiding redistribution of restricted content without permission

Security

No external code execution beyond invoking pandoc (if installed). If you suspect a vulnerability, open a private security advisory on GitHub.

License

MIT

Acknowledgements

• Pixiv platform & creators
• Pandoc project (for robust conversion tools)
• Open-source ecosystem (yargs, sharp, etc.)

Enjoy clean, faithful offline copies of Pixiv novels. If this helps you, consider starring the repo: https://github.com/thr12345/pixiv-novel-dl