PixivUtil server is a self-hosted, containerized server solution which provides PixivUtil2 content download operations through an HTTP API interface.
The scope of PixivUtil server covers only key Pixiv-related operations within a uv environment or Docker cluster. Non-Pixiv APIs, such as Fantia or Fanbox, are not supported, as they cannot be reliably tested.
Before installing, prepare the PixivUtil2 git submodule:
git submodule update --init --recursiveThis will clone the PixivUtil2 repository.
Build and run with Docker compose. A pixiv cookie is required at PIXIVUTIL_COOKIE.
docker compose up --build --remove-orphansThis project uses uv inside the Docker image to install and run the app. Make a request to download an artwork:
curl -X POST http://localhost:8000/api/queue/download/artwork/{artwork-id-here}/api/download/* remains available as a deprecated compatibility alias.
If PIXIVUTIL_SERVER_API_KEY is not set (or is empty), API key authentication is disabled. If it is set, the request above needs an Authorization: Bearer <your-api-key> header.
An nginx configuration file is attached for your reverse proxy reference.
Endpoints to get metadata from the PixivUtil2 database.
For example, the server supports the following endpoints:
- Get image metadata by ID
- Get member metadata by ID
- Get tag metadata by ID
- Get series metadata by ID
API endpoints to inspect, replay, and purge failed worker messages in the dead letter queue.
API endpoints to queue content (artwork) downloads for worker from server.
The following jobs are supported via PixivUtil server API:
- Download artworks by member ID
- Download artwork by image ID
- Download artworks by tag
- Delete an artwork from the database and filesystem
All queue endpoints accept an optional priority query parameter (1-3, where 3 is highest). Defaults are chosen per endpoint so that cheap single-artwork requests outrank long bulk crawls.
Health-related API endpoints, such as healthcheck for Docker containers.
API endpoints to queue metadata downloads for worker from server. Metadata includes artist, artwork, series, and tag.
This is helpful when you have an artwork downloaded, but it's old/outdated and you want to re-fetch only the metadata.
Prometheus metrics endpoint, covering database counts, disk and system usage, queue/DLQ depth, and HTTP request statistics.
Server-related API endpoints, such as get cookie, update cookie, delete database, and delete downloads.
PixivUtil server applies a downstream server flavor of PixivUtil2 called "Server Mode" PixivUtil2. Server Mode applies additional configuration changes to ensure that downloaded Pixiv data is more reliable and available. See the server mode README here.
For further configuration, apply them at .pixivUtil2/conf/conf.ini (refer to Pixivutil2 configuration options). You should shutdown PixivUtil server and remove the backup .ini file before applying the changes and restarting.
Supported environment variables, defined across PixivServer/config/:
| Variable | Default | Purpose |
|---|---|---|
PIXIVUTIL_COOKIE |
(none) | Pixiv session cookie. Required. |
PIXIVUTIL_SERVER_API_KEY |
(unset) | Enables API key authentication when set. |
PIXIVUTIL_SERVER_ENV |
production |
production or development. See Environments. |
RABBITMQ_BROKER_URL |
amqp://guest:guest@rabbitmq:5672 |
Celery broker. |
RABBITMQ_MANAGEMENT_URL |
http://guest:guest@rabbitmq:15672 |
Used to collect queue depth metrics. |
PUID, PGID, and CELERYBEAT_SCHEDULE are consumed by the container entrypoint and Celery beat rather than by the application config objects; see docker-compose.yml.
Docker user mapping:
PUIDandPGIDset the UID/GID used by the server and worker containers (default1000:1000).
Any directories that were previously root should be set to the desired UID/GID pair.
If there are file permission issues, you may override the user entrypoint and maintain the container user as root.
entrypoint: ["uv", "run"] # use this if you want to keep a non-root user.Set PIXIVUTIL_SERVER_API_KEY to enable API key authentication for protected endpoints.
Header format:
Authorization: Bearer <your-api-key>
PIXIVUTIL_SERVER_ENV selects server environment.
production(default)development
If set to development, enables debug logging and mounts /api/dev/* router with a set of testing endpoints.
PixivUtil server is a Python project based on PixivUtil2 as its API client engine. PixivUtil2 is a separate git repository added to this as a submodule.
PixivUtil server as a service consists of 3 microservices: the PixivUtil API server, PixivUtil worker, and RabbitMQ queue. The server receives API requests from the user/client, and passes them as long-running jobs to a single-process worker which handles them one at a time via the queue, controlling API volumes and avoiding rate limit violations.
The web server component uses FastAPI, and the worker component uses Celery listening to FastAPI publishes through a rabbit queue.
To support durable messages with RabbitMQ, a timeout configuration is applied for the queue server. See issue.
PixivUtil Server applies server-managed SQLite runtime settings. These settings are applied at connection startup in both the Pixiv service layer and repository layer, and allow for better concurrent reads from the API layer.
PRAGMA journal_mode=WAL is set to improve database concurrency handling. While not a server that handles many users, PixivServer is expected to handle reasonably concurrent reads while worker is performing single writes.
PRAGMA synchronous=NORMAL is a consequence of applying WAL to the database for performance purposes.
PRAGMA busy_timeout=30000 is set to not throw an error immediately when the database is locked.
uv is the recommended Python project manager for development:
uv sync --extra pixivutil2 # sync dev + PixivUtil2 dependencies
uv run pytest tests # run tests
uv run ruff check . # run ruff lint check
uv run pyright # run type checksThe project also uses uv as the build runtime with uv_build, which significantly speeds up build times. On a raspberry pi, building the Dockerfile with uv_build takes ~5m, 3m less than with default pip.
PixivUtil client is an asynchronous API client for PixivUtil server. See the client README.