gallery-dl Pixiv Guide

The official Pixiv extractor covers more than a single artwork. The supported-sites reference lists user profiles, individual images, favorites, follows, rankings, searches, series, Sketch, pixivision, background images, avatars, and other Pixiv-specific paths. Treat each URL as a different scope. A profile can produce many works, while an individual artwork is a safer first test.

Copy the canonical www.pixiv.net URL from the page you are allowed to access, quote it in the shell, and simulate extraction before writing files. The simulation shows whether the installed release recognizes the URL, whether the page needs authentication, and which media records would be selected. It is an inspection step, not proof that every item in a large collection will remain available.

gallery-dl --simulate "https://www.pixiv.net/en/artworks/ARTWORK_ID"

gallery-dl --simulate "https://www.pixiv.net/en/users/USER_ID"

gallery-dl -K "https://www.pixiv.net/en/artworks/ARTWORK_ID"

Pixiv can require a signed-in browser session for pages or media that anonymous requests cannot open. Sign in through the normal Pixiv website in a browser profile you control, confirm that the target page opens there, and let gallery-dl read the local cookie store. A cookie selector mirrors the access your account already has; it does not grant permission to private works or bypass a challenge.

Close the browser if its cookie database is locked, and select the profile that actually contains the active Pixiv session. If a command worked yesterday but now reports an authentication error, check the session, the profile name, the URL scope, and the installed gallery-dl version separately. Never paste raw cookie values, browser databases, refresh tokens, or passwords into a public config or bug report.

• Confirm the same profile can open the Pixiv page normally.
• Close the browser when the local cookie database is locked.
• Keep cookie values and account identifiers on your own device.
• Treat private, deleted, age-restricted, or challenged content as unavailable when the account cannot open it.

gallery-dl --cookies-from-browser firefox --simulate "https://www.pixiv.net/en/users/USER_ID"

gallery-dl --cookies-from-browser chrome --simulate "https://www.pixiv.net/en/users/USER_ID"

gallery-dl --cookies-from-browser edge --simulate "https://www.pixiv.net/en/users/USER_ID"

A successful extractor response is only the beginning.

Keep the destination outside a temporary browser profile and avoid mixing unrelated accounts in one folder.

gallery-dl --cookies-from-browser firefox --range "1-10" --destination "D:/Media/Pixiv" "https://www.pixiv.net/en/users/USER_ID"

gallery-dl -K "https://www.pixiv.net/en/artworks/ARTWORK_ID"

gallery-dl --simulate --config-ignore "https://www.pixiv.net/en/artworks/ARTWORK_ID"

Once a small run is correct, add --download-archive with one stable local file. The archive stores successful extractor identifiers and lets later runs skip items that already completed. It is not a backup of the media, and it should not be deleted just because a later URL returned no files. An empty result may mean the scope changed, the content is unavailable, a filter is too narrow, or the archive already contains the matching IDs.

Increase the range gradually and inspect the output after each change. Pixiv profiles, rankings, searches, and series can change while you work, so a repeated command is not guaranteed to describe the same result set. If the job is shared between machines, back up the archive deliberately, keep the path stable, and avoid copying browser credentials along with it.

• Use one archive path for one recurring job.
• Back up the archive as a record, not as a media replacement.
• Increase ranges only after the selected files and folders look correct.
• Do not interpret every empty result as a Pixiv extractor failure.

gallery-dl --cookies-from-browser firefox --range "1-25" --download-archive "pixiv.sqlite3" "https://www.pixiv.net/en/users/USER_ID"

gallery-dl --write-metadata --download-archive "pixiv.sqlite3" "https://www.pixiv.net/en/artworks/ARTWORK_ID"

gallery-dl --download-archive "pixiv-diagnostic.sqlite3" --simulate "URL"

Move stable choices into a config file only after the command-line version succeeds.

Validate the JSON and check the active file before blaming Pixiv.

{
  "extractor": {
    "base-directory": "D:/Media/Pixiv",
    "archive": "D:/Media/Pixiv/pixiv.sqlite3"
  }
}

gallery-dl --config-status

gallery-dl --config-ignore --simulate "https://www.pixiv.net/en/artworks/ARTWORK_ID"

Treat authentication, rate limits, URL recognition, filters, and archive skips as different problems.

Compare the same URL with --config-ignore and --simulate, then add one setting at a time.

• Use only content and accounts you are authorized to access and use.
• Do not share cookies, tokens, private URLs, or unredacted logs.
• Keep the first test small and simulated.
• Respect Pixiv rules, creator rights, privacy, and rate limits.