Configuration options¶
Configuration for PixivFE is loaded from a configuration file, environment variables, and command-line flags.
For most settings, values are loaded according to the following order of precedence, from highest to lowest:
- Environment variables (e.g.,
PIXIVFE_HOST
) - Values from the configuration file (e.g.,
config.yaml
) - Default values
The path to the configuration file is an exception. It is determined separately with its own order of precedence:
- The
-config
command-line flag - The
PIXIVFE_CONFIGFILE
environment variable - The default path (
./config.yaml
or./config.yml
)
Configuration file¶
By default, PixivFE loads configuration from a config.yaml
file in the current working directory. If config.yaml
is not found, the application then checks for config.yml
.
The following is an example of a minimal configuration file:
A complete list of configuration options is available in the config.yaml.example
file in the repository. You can copy this file to config.yaml
and customize it.
A custom path to the configuration file can be set using the -config
flag.
Bash | |
---|---|
The PIXIVFE_CONFIGFILE
environment variable can also be used to set a custom path.
Bash | |
---|---|
Environment variables¶
Any configuration option can be supplied as an environment variable. Environment variables have a higher precedence than the configuration file. If an option is set in both locations, the value from the environment variable is used.
For example, the following command sets the token and the port:
Bash | |
---|---|
Refer to the .env.example
file in the repository for a complete list of environment variables. You can copy this file to .env
and customize it.
Config file format:
PIXIVFE_UNIXSOCKET_USER
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
unixSocketUser |
PIXIVFE_UNIXSOCKET_USER |
No | - | Username or UID |
Specifies user owner applied to the UNIX socket.
PIXIVFE_UNIXSOCKET_GROUP
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
unixSocketGroup |
PIXIVFE_UNIXSOCKET_GROUP |
No | - | Group name or GID |
Specifies group owner applied to the UNIX socket.
PIXIVFE_TOKEN
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
token |
PIXIVFE_TOKEN |
Yes | - | Comma-separated tokens (multiple allowed) |
PHPSESSID
cookie(s) for authentication with the pixiv API.
Multiple tokens can be specified.
Environment variable format:
Bash | |
---|---|
Config file format:
Content proxy servers¶
These options must be nested under a contentProxies:
block in config.yaml
.
pixiv requires Referer: https://www.pixiv.net/
in the HTTP request headers to fetch images from their servers.
If any of these individual settings is not set, the built-in proxy will be used for that specific service.
For setting up your own proxy server, refer to hosting an image proxy server. Alternatively, see the list of public image proxies if you prefer to use an existing deployment.
PIXIVFE_IMAGEPROXY
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
imageProxy |
PIXIVFE_IMAGEPROXY |
No | (built-in proxy) | URL |
The URL of a server that acts as a reverse proxy for i.pximg.net.
PIXIVFE_STATICPROXY
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
staticProxy |
PIXIVFE_STATICPROXY |
No | (built-in proxy) | URL |
The URL of a server that acts as a reverse proxy for s.pximg.net.
PIXIVFE_UGOIRAPROXY
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
ugoiraProxy |
PIXIVFE_UGOIRAPROXY |
No | (built-in proxy) | URL |
The URL of a server that acts as a reverse proxy for t-hk.ugoira.com.
Token management¶
These options must be nested under a tokenManager:
block in config.yaml
.
PixivFE implements exponential backoff for token management to manage rate limiting.
The following environment variables control how PixivFE manages token timeouts when a token encounters repeated failures. The backoff time for a token starts at the base timeout and doubles with each failure, up to the maximum backoff time.
PIXIVFE_TOKEN_LOAD_BALANCING
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
tokenLoadBalancing |
PIXIVFE_TOKEN_LOAD_BALANCING |
No | round-robin |
round-robin , random , least-recently-used |
Specifies the method for selecting tokens when multiple tokens are provided in PIXIVFE_TOKEN
.
round-robin
: Tokens are used in a circular order.random
: A random token is selected for each request.least-recently-used
: The token that hasn't been used for the longest time is selected.
This option is useful when you have multiple pixiv accounts and want to distribute the load across them.
PIXIVFE_TOKEN_MAX_RETRIES
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
tokenMaxRetries |
PIXIVFE_TOKEN_MAX_RETRIES |
No | 5 |
Integer |
Maximum retry attempts before marking a token as unavailable.
PIXIVFE_TOKEN_BASE_TIMEOUT
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
tokenBaseTimeout |
PIXIVFE_TOKEN_BASE_TIMEOUT |
No | 1000ms |
time.Duration |
Initial backoff duration on token failure.
PIXIVFE_TOKEN_MAX_BACKOFF_TIME
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
tokenMaxBackoffTime |
PIXIVFE_TOKEN_MAX_BACKOFF_TIME |
No | 32000ms |
time.Duration |
Maximum backoff duration during exponential retry.
API response caching¶
These options must be nested under a cache:
block in config.yaml
.
PixivFE implements a caching system for API responses to improve performance. The cache uses a Least Recently Used (LRU) eviction policy.
Each cache entry is stored with an expiration time. When a cached item is accessed, its expiration time is checked. If the item has expired, it is treated as a cache miss, and a new request is made to the Pixiv API.
To ensure that responses are properly isolated between different users, the cache key for each item is generated based on both the URL of the request and the value of the user's pixivfe-Token
cookie.
PIXIVFE_CACHE_ENABLED
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
cacheEnabled |
PIXIVFE_CACHE_ENABLED |
No | false |
Boolean |
Controls whether the caching system is enabled.
When disabled, all requests will be sent directly to the Pixiv API without caching.
Other caching configuration variables will have no effect if this variable is set to false
.
PIXIVFE_CACHE_SIZE
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
cacheSize |
PIXIVFE_CACHE_SIZE |
No | 100 |
Integer |
Specifies the maximum number of items that can be stored in the LRU cache.
This limits the memory usage of the cache.
When the cache reaches this size, the least recently used items will be evicted to make room for new entries.
PIXIVFE_CACHE_TTL
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
cacheTTL |
PIXIVFE_CACHE_TTL |
No | 60m |
time.Duration |
Specifies the default Time To Live (TTL) for cached items.
This is the duration for which an item remains valid in the cache before it's considered stale and needs to be fetched again from the pixiv API.
The TTL is applied to most API responses and can safely be set to a high value. Dynamic content such as Discovery and Newest is never cached.
HTTP caching¶
These options must be nested under a httpCache:
block in config.yaml
.
These cache control settings affect HTTP caching behavior and are separate from PixivFE's internal API response cache.
PIXIVFE_CACHE_CONTROL_MAX_AGE
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
cacheControlMaxAge |
PIXIVFE_CACHE_CONTROL_MAX_AGE |
No | 30s |
time.Duration |
Controls the max-age
directive in the Cache-Control response header for artwork pages.
This determines how long browsers should cache the page before revalidating with the server.
PIXIVFE_CACHE_CONTROL_STALE_WHILE_REVALIDATE
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
cacheControlStaleWhileRevalidate |
PIXIVFE_CACHE_CONTROL_STALE_WHILE_REVALIDATE |
No | 60s |
time.Duration |
Controls the stale-while-revalidate
directive in the Cache-Control response header for artwork pages.
This allows browsers to show stale content while fetching a fresh version in the background.
Request parameters¶
These options must be nested under a request:
block in config.yaml
.
PIXIVFE_ACCEPTLANGUAGE
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
acceptLanguage |
PIXIVFE_ACCEPTLANGUAGE |
No | en-US,en;q=0.5 |
Accept-Language value |
The value of the Accept-Language
header used for requests to pixiv's API.
Change this to modify the response language.
Response behavior¶
These options must be nested under a response:
block in config.yaml
.
PIXIVFE_EARLY_HINTS_RESPONSES_ENABLED
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
earlyHintsResponsesEnabled |
PIXIVFE_EARLY_HINTS_RESPONSES_ENABLED |
No | false |
Boolean |
Controls whether PixivFE's internal HTTP server returns HTTP 103 Early Hints
informational responses.
Used to return Link
headers to the client for preloading images while the server is busy preparing the main HTML response.
Warning
Some reverse proxies may not handle informational responses such as HTTP 103 correctly.
Features¶
These options must be nested under a feature:
block in config.yaml
.
PIXIVFE_POPULAR_SEARCH_ENABLED
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
popularSearchEnabled |
PIXIVFE_POPULAR_SEARCH_ENABLED |
No | false |
Boolean |
Controls whether searching by popularity for a given tag is enabled.
Warning
This feature requires several API calls for each search.
API response caching via PIXIVFE_CACHE_ENABLED=true
is recommended when this is enabled.
PIXIVFE_FAST_TAG_SUGGESTIONS
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
fastTagSuggestions |
PIXIVFE_FAST_TAG_SUGGESTIONS |
No | false |
Boolean |
Controls whether to use a fast tag suggestion endpoint with lower latency.
When enabled, tag completion requests will use a Vercel-cached proxy endpoint (https://tag-suggestions.vercel.app/api/proxy
) instead of the default pixiv endpoint (https://www.pixiv.net/rpc/cps.php
).
This can improve response times for tag suggestions through Vercel's edge caching.
Instance information¶
These options must be nested under a instance:
block in config.yaml
.
PIXIVFE_REPO_URL
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
repoUrl |
PIXIVFE_REPO_URL |
No | https://codeberg.org/PixivFE/PixivFE |
URL |
The URL of the PixivFE source code repository.
This is used to provide links to the application source code and specific commit information.
Change this if you're running a fork of PixivFE to link to your own repository instead.
Network proxy¶
Used to set the proxy server that PixivFE will use for all requests.
Not to be confused with the image proxy, which is used to comply with the Referer
check required by i.pximg.net
.
Requests use the proxy specified in the configuration option that matches the scheme of the request (HTTP_PROXY
or HTTPS_PROXY
).
This selection is based on the scheme of the request being made, not on the protocol used by the proxy server itself.
Note
These options are currently only available through environment variables.
HTTPS_PROXY
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
- | HTTPS_PROXY |
No | - | Proxy URL |
Proxy server used for requests made over HTTPS.
HTTP_PROXY
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
- | HTTP_PROXY |
No | - | Proxy URL |
Proxy server used for requests made over plain HTTP.
Rate limiter¶
These options must be nested under a limiter:
block in config.yaml
.
PixivFE includes a configurable rate limiter that can help protect your instance from abuse. The limiter uses a network-based approach that groups clients by IP network and applies dynamic rate limits based on client behavior.
PIXIVFE_LIMITER_ENABLED
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
enabled |
PIXIVFE_LIMITER_ENABLED |
No | false |
Boolean |
Controls whether the rate limiter is enabled.
When enabled, the rate limiter middleware will filter HTTP requests based on various criteria and apply rate limits to control traffic. Other limiter options will only take effect if this is set to true
.
PIXIVFE_LIMITER_PASS_IPS
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
passList |
PIXIVFE_LIMITER_PASS_IPS |
No | - | Array/comma-separated list of IPs/CIDRs |
A list of IP addresses or CIDR ranges that bypass all rate limiting checks.
Environment variable format:
Bash | |
---|---|
Config file format:
Requests from these IPs will be allowed without any rate limiting restrictions.
PIXIVFE_LIMITER_BLOCK_IPS
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
blockList |
PIXIVFE_LIMITER_BLOCK_IPS |
No | - | Array/comma-separated list of IPs/CIDRs |
A list of IP addresses or CIDR ranges that are always blocked.
Environment variable format:
Bash | |
---|---|
Config file format:
Requests from these IPs will be denied with a 401 Unauthorized response.
PIXIVFE_LIMITER_FILTER_LOCAL
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
filterLocal |
PIXIVFE_LIMITER_FILTER_LOCAL |
No | false |
Boolean |
Controls whether link-local addresses (IPv4: 169.254.0.0/16
, IPv6: fe80::/10
) are subject to rate limiting.
When true
(enabled), link-local addresses will be rate limited according to the same rules as other addresses. When false
(disabled, default), link-local addresses will bypass rate limiting checks.
PIXIVFE_LIMITER_IPV4_PREFIX
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
ipv4Prefix |
PIXIVFE_LIMITER_IPV4_PREFIX |
No | 24 |
Integer (0-32) |
The network prefix length used to group IPv4 addresses for rate limiting purposes.
For example, with the default value of 24
, all addresses within the same /24
network (e.g., 192.168.1.0/24
) share the same rate limit bucket.
Higher values provide more granular control via smaller groups. Lower values group more addresses together.
PIXIVFE_LIMITER_IPV6_PREFIX
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
ipv6Prefix |
PIXIVFE_LIMITER_IPV6_PREFIX |
No | 48 |
Integer (0-128) |
The network prefix length used to group IPv6 addresses for rate limiting purposes.
For example, with the default value of 48
, all addresses within the same /48
network share the same rate limit bucket.
Higher values provide more granular control via smaller groups. Lower values group more addresses together.
PIXIVFE_LIMITER_CHECK_HEADERS
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
checkHeaders |
PIXIVFE_LIMITER_CHECK_HEADERS |
No | true |
Boolean |
Controls whether specific HTTP request headers are checked for patterns commonly associated with bots.
If enabled, clients with matching headers will be blocked.
PIXIVFE_LIMITER_DETECTION_METHOD
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
detectionMethod |
PIXIVFE_LIMITER_DETECTION_METHOD |
No | "" (none) |
"" (none), linktoken , turnstile |
Specifies the bot detection method to use. This method determines how clients are verified and whether they are marked as "suspicious," which can lead to stricter rate limits.
""
(or not set, effectively 'none'): No specific challenge method is used. Clients are always treated as non-suspicious, but clients can still be blocked by headers ifPIXIVFE_LIMITER_CHECK_HEADERS
is enabled.linktoken
: Enables the "link token" bot detection logic. PixivFE embeds a unique token in HTML pages as a CSS resource. Real browsers will fetch this resource and receive apixivfe-Ping
cookie that proves they can properly render web pages. Requests without a valid cookie are considered suspicious and limited more heavily. This helps distinguish between actual users and simple bots. RequiresPIXIVFE_LIMITER_PING_HMAC
.turnstile
: Uses Cloudflare Turnstile for bot detection. Clients will be presented with a Turnstile challenge. Upon successful verification, apixivfe-Ping
cookie is set. Requests without a valid cookie are considered suspicious and limited more heavily. RequiresPIXIVFE_LIMITER_PING_HMAC
,PIXIVFE_LIMITER_TURNSTILE_SITE_KEY
, andPIXIVFE_LIMITER_TURNSTILE_SECRET_KEY
.
PIXIVFE_LIMITER_PING_HMAC
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
pingHMAC |
PIXIVFE_LIMITER_PING_HMAC |
Yes (if detectionMethod is linktoken or turnstile ) |
- | String (32+ characters) |
The secret key used to sign and verify pixivfe-Ping
cookies. These cookies are used by both the linktoken
and turnstile
detection methods to remember successfully verified clients.
This value must be at least 32 characters long and should be kept secret.
Warning
This setting is required and must be set if detectionMethod
is linktoken
or turnstile
.
Failure to set this will prevent PixivFE from starting when these methods are active.
PIXIVFE_LIMITER_TURNSTILE_SITEKEY
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
turnstileSitekey |
PIXIVFE_LIMITER_TURNSTILE_SITEKEY |
Yes (if detectionMethod is turnstile ) |
- | String |
The sitekey for Cloudflare Turnstile. This is required if detectionMethod
is set to turnstile
.
You can obtain this from your Cloudflare dashboard when setting up a Turnstile widget.
PIXIVFE_LIMITER_TURNSTILE_SECRET_KEY
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
turnstileSecretKey |
PIXIVFE_LIMITER_TURNSTILE_SECRET_KEY |
Yes (if detectionMethod is turnstile ) |
- | String |
The secret key for Cloudflare Turnstile. This is required if detectionMethod
is set to turnstile
.
You can obtain this from your Cloudflare dashboard when setting up a Turnstile widget. This key should be kept confidential.
Logging¶
These options must be nested under a log:
block in config.yaml
.
Options to configure zerolog, which PixivFE uses for structured logging.
PIXIVFE_LOG_LEVEL
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
logLevel |
PIXIVFE_LOG_LEVEL |
No | info |
debug , info , warn , error |
Sets the minimum level of log messages to output.
debug
: Includes all log messages, including detailed debug information.info
: Includes informational messages, warnings, and errors.warn
: Includes only warning and error messages.error
: Includes only error messages.
PIXIVFE_LOG_OUTPUTS
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
logOutputs |
PIXIVFE_LOG_OUTPUTS |
No | /dev/stderr |
Array/comma-separated list of file paths |
Specifies where log messages should be sent. This can be a single output or multiple. Special values /dev/stdout
and /dev/stderr
are supported.
Environment variable format:
Bash | |
---|---|
Config file format:
PIXIVFE_LOG_FORMAT
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
logFormat |
PIXIVFE_LOG_FORMAT |
No | console |
console , json |
Determines the format of log messages.
console
: Human-readable format suitable for console outputjson
: Structured JSON format, useful for log parsing and analysis tools
Development¶
These options must be nested under a development:
block in config.yaml
.
PIXIVFE_DEV
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
inDevelopment |
PIXIVFE_DEV |
No | false |
Boolean |
Set to true
to enable development mode.
This sets the default log level to debug
and disables logging for static asset and image proxy paths to reduce noise during development.
PIXIVFE_SAVE_RESPONSES_ENABLED
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
saveResponsesEnabled |
PIXIVFE_SAVE_RESPONSES_ENABLED |
No | false |
Boolean |
Controls whether API responses from pixiv are saved to disk.
When enabled, responses will be saved to the directory specified by PIXIVFE_RESPONSE_SAVE_LOCATION
.
PIXIVFE_RESPONSE_SAVE_LOCATION
¶
YAML name | Environment variable | Required | Default | Options |
---|---|---|---|---|
responseSaveLocation |
PIXIVFE_RESPONSE_SAVE_LOCATION |
No | /tmp/pixivfe/responses |
File path |
Defines where responses from the pixiv API are saved when PIXIVFE_SAVE_RESPONSES_ENABLED
is enabled.