piximan - Pixiv Manager

Pixiv batch downloader and local collection viewer. Preserve your favorite art with ease!

Note

The project is currently in active development

• The downloader CLI tool is pretty stable and feature-rich now
• Collection viewer GUI is still being figured out

Installation

Arch Linux

piximan and piximan-bin packages are available in the AUR.

Linux / Windows / MacOS

Download a binary from the latest release page

Getting started with piximan CLI

Downloader Features

• Download illustrations / manga / ugoira / novels
• Download different sizes (resolutions) of the illustrations / manga
• Download orginal or English-translated work metadata if available
• Download your bookmarks or bookmarks of another user
• Download by work ID
• Download from list
• Filter downloaded works with download rules
• Avoid downloading duplicate works by providing path to your collection
• Infer work IDs from existing collection paths for easy migration to piximan metadata
• Interactive mode for download and configuration CLI
• Use substitutions in download path: {title} / {id} / {user} / {user-id} / etc.
• Make requests concurrently when it's possible without bothering the Pixiv servers too much
• Authorize requests with your session ID, piximan will try to use it as few as possible
• Encrypt your session ID with a master password
• Adjust request delays and concurrency limits

Authorization

Note

If you only download works without age restriction and don't need to fetch user bookmarks, the downloader is usable without authorization.

For some requests Pixiv requires you to be authorized. For example, to fetch frames for R-18 ugoira you must have the R-18 option checked in your profile. To authorize these requests you need to configure the session ID.

You can get session ID from your browser cookies right now:

• Go to https://www.pixiv.net
• On the website press F12 to access the devtools panel
• In the devtools panel switch to the Application tab (for Chrome) / Storage tab (for Firefox)
• Expand the Cookies section and select https://www.pixiv.net origin
• Find the row named PHPSESSID - this is your cookie
• Copy the value of the cookie to the clipboard

Now open the terminal and run the command to enter interractive configuration mode:

piximan config

Paste the copied session ID and then specify the master password if you want.

Downloading with interactive mode

The easiest way to use the tool is with interactive mode. To enter it run the command, then answer the questions about what to download and where to save the files:

piximan download

Downloading a work by ID

You're ready to go! Try out piximan by downloading an artwork from pixiv:

piximan download \
  --id 584231 \
  --path './artworks/{user} ({user-id})/{title} ({id})'

Downloading a novel is as simple:

piximan download \
  --id 584231 \
  --type novel \
  --path './novels/{user} ({user-id})/{title} ({id})'

Downloading bookmarks

Note

For downloading any bookmarks you need to be authorized (configure the session ID).

You can download your public artwork bookmarks like this:

piximan download \
  --bookmarks my \
  --path './bookmarks/{user} ({user-id})/{title} ({id})'

You can also specify --type novel to download novel bookmarks and --private to download private bookmarks.

piximan download \
  --bookmarks my \
  --type novel \
  --private \
  --path './bookmarks/{user} ({user-id})/{title} ({id})'

You can also specify a user-assigned tag or download only a specified range. This example will download your public bookmarks with tag 'お気に入り' from 101th to 200th latest:

piximan download \
  --bookmarks my \
  --tag 'お気に入り' \
  --from 100 \
  --to 200 \
  --path './bookmarks/{user} ({user-id})/{title} ({id})'

You can also download public bookmarks of any user knowing their ID. For example, this will download novel bookmarks of user 12345:

piximan download \
  --bookmarks 12345 \
  --type novel \
  --path './bookmarks/{user} ({user-id})/{title} ({id})'

Downloading from list

You can specify a queue for downloader using YAML format such as:

./list.yaml

# This will download two artworks with ID 12345 and 23456
- { id: 12345, type: artwork }
- { id: 23456, type: artwork }

# This will override provided downloader arguments
- id: 34567
  type: artwork
  size: 1
  only-meta: false
  paths: ['./special artwork']
- id: 45678
  type: novel
  only-meta: true
  paths: ['./special novel']

Start downloading with the command:

piximan download \
  --list './list.yaml' \
  --path './artworks/{user} ({user-id})/{title} ({id})'

Inferring work IDs from path

You can infer the IDs of works from the given path. For example, this is useful for updating the metadata in the existing collection when coupled with the --only-meta flag:

piximan download --infer-id './artworks/*/* ({id})' --only-meta

Downloading rules

Rules are used to filter which works should be downloaded and defined in YAML format. All rules are optional, and if multiple rules are defined, the work should match all of them to be downloaded (AND). Any array matches any of its elements (OR).

Here's an example of all available rules:

ids: [12345, 23456]
not_ids: [34567, 45678]
title_contains: ['cute', 'cat']
title_not_contains: ['ugly', 'dog']
title_regexp: '^.*[0-9]+$'
kinds: ['illust', 'manga', 'ugoira', 'novel']
description_contains: ['hello', 'world']
description_not_contains: ['goodbye', 'universe']
description_regexp: '^.*[0-9]+$'
user_ids: [12345, 23456]
not_user_ids: [34567, 45678]
user_names: ['fekoneko', 'somecoolartist']
not_user_names: ['notsocoolartist', 'notme']
restrictions: ['none', 'R-18', 'R-18G']
ai: false
original: true
pages_less_than: 50
pages_more_than: 3
views_less_than: 10000
views_more_than: 1000
bookmarks_less_than: 1000
bookmarks_more_than: 100
likes_less_than: 500
likes_more_than: 50
comments_less_than: 10
comments_more_than: 2
uploaded_before: 2022-01-01T00:00:00Z00:00
uploaded_after: 2010-01-01T00:00:00Z00:00
series: true
series_ids: [12345, 23456]
not_series_ids: [34567, 45678]
series_title_contains: ['cute', 'cat']
series_title_not_contains: ['ugly', 'dog']
series_title_regexp: '^.*[0-9]+$'
tags: ['お気に入り', '東方']
not_tags: ['おっぱい', 'AI生成']

When downloading, specify the rules with --rules flag:

piximan download --id 12345 --rules './rules.yaml'

Syncing bookmarks with existing collection

You can skip works already present in the directory with --skip flag:

piximan download --bookmarks my --skip '.' --path './{user-id}/{id}'

Infer ID pattern can be provided here as well (see --infer-id flag). Note that in this case all matched work IDs will be assumed to be of type provided with --type flag:

piximan download --bookmarks my --skip './*/{id}' --path './{user-id}/{id}'

While the above commands will skip already downloaded works, piximan will need to fetch the list of all your bookmarks to ensure there isn't some older one that isn't present in the collection.

Flag --until-skip will tell the downloader to stop crawling new bookmark pages once it encounters a fully skipped one. This may greatly reduce the number of authorized requests to pixiv.net.

So for syncing your new bookmarks once in a while you can use the downloader like this:

piximan download --bookmarks my --skip '.' --until-skip --path './{user-id}/{id}'

Help

To see other options and examples use the help command in your terminal:

piximan help download
piximan help config

Development

Use make to run and build the project:

make run                 # Run piximan GUI
make run ARGS='download' # Run piximan CLI tool with the arguments
make build               # Build for all platforms
make build:current       # Build for current platform
make build:$PLATFORM     # Build for $PLATFORM

Related projects

This project is the next iteration on my way to perfect local Pixiv app. So far I tried:

• React Native for Windows
• Electron + React
• Tauri + React + Rust
• Rust + GTK
• Go + GTK <- this one