Configuration options

PixivFE can be configured using environment variables or loading from a config file.

Configuration File

By default, PixivFE tries to load the configuration from a config.yml file in the current working directory, if it exists. You can create this file and put any of the configuration options below in it. Here is an example of a configuration file:

# Required fields for a working instance
token: 123456_arstdhnei
port: 8282

# Other configs...
inDevelopment: true
imageProxy: "https://i.yuki.sh"

You can specify a different path for the configuration file using the -config option. The supplied config file must be in YAML format. Example:

# Build PixivFE and execute
go build
./pixivfe -config personalInstance.yml

# You can do `./pixivfe -h` to get help

It is also possible to use an environment variable to specify the configuration file:

# Build PixivFE and execute
go build
PIXIVFE_CONFIGFILE=personalInstance.yml ./pixivfe

Options are listed in the Available Options section below.

Environment Variables

Any configuration option can be set as an environment variable. If a configuration option was both set in configuration file and/or in an environment variable, PixivFE will prioritize using environment variables.

For example, to quickly set up PixivFE:

PIXIVFE_TOKEN=123456_arstdhnei PIXIVFE_PORT=8282 ./pixivfe

Available Options

Basic options

PIXIVFE_CONFIGFILE

Config name: none

Required: No

This environment variable specifies the path of a YAML file, which will be used to configure PixivFE.

If this variable is left empty, it will default to ./config.yml.

PIXIVFE_PORT or PIXIVFE_UNIXSOCKET

Config name: port | unixSocket

Required: No

• PIXIVFE_PORT: Port to listen on, e.g., PIXIVFE_PORT=8282.
• PIXIVFE_UNIXSOCKET: UNIX socket to listen on, e.g., PIXIVFE_UNIXSOCKET=/tmp/pixivfe.sock.

If neither are provided, PixivFE will listen on port 8282 by default.

PIXIVFE_TOKEN

Config name: token

Required: Yes

Your Pixiv account cookie, used by PixivFE for authorization to fully access Pixiv's Ajax API. This variable can contain multiple tokens separated by commas, which is useful for load balancing across multiple Pixiv accounts.

Example:

PIXIVFE_TOKEN=123456_AaBbccDDeeFFggHHIiJjkkllmMnnooPP,789012_QqRrSsTtUuVvWwXxYyZz

See the Obtaining the PIXIVFE_TOKEN cookie guide for detailed instructions.

PIXIVFE_HOST

Config name: host

Required: No (ignored if PIXIVFE_UNIXSOCKET is set)

Note

If you're not using a reverse proxy or running PixivFE inside Docker, you should set PIXIVFE_HOST=0.0.0.0. This will allow PixivFE to accept connections from any IP address or hostname. If you don't set this, PixivFE will refuse direct connections from other machines or devices on your network.

This setting specifies the hostname or IP address that PixivFE should listen on and accept incoming connections from. For example, if you want PixivFE to only accept connections from the same machine (your local computer), you can set PIXIVFE_HOST=localhost.

PIXIVFE_REPO_URL

Config name: repoUrl

Required: No

Default: https://codeberg.org/VnPower/PixivFE

The URL of the PixivFE source code repository. This is used in the about page to provide links to the project's source code and specific commit information. You can change this if you're running a fork of PixivFE and want to link to your own repository instead.

PIXIVFE_REQUESTLIMIT

Config name: requestLimit

Required: No

Request limit per half-minute.

Set to a number to enable the built-in rate limiter, e.g., PIXIVFE_REQUESTLIMIT=15.

It's recommended to enable rate limiting in the reverse proxy in front of PixivFE rather than using this.

PIXIVFE_IMAGEPROXY

Config name: imageProxy

Required: No

Default: Uses the built-in proxy.

Note

The protocol must be included in the URL, e.g., https://piximg.example.com, where https:// is the protocol used.

The URL of the image proxy server. Pixiv requires Referer: https://www.pixiv.net/ in the HTTP request headers to fetch images directly. Set this variable if you wish to use an external image proxy or are unable to get images directly from Pixiv.

See hosting an image proxy server or the list of public image proxies.

PIXIVFE_ACCEPTLANGUAGE

Config name: acceptLanguage

Required: No

Default: en-US,en;q=0.5

The value of the Accept-Language header used for requests to Pixiv's API. Change this to modify the response language.

PIXIVFE_TOKEN_LOAD_BALANCING

Config name: tokenLoadBalancing

Required: No

Default: round-robin

Specifies the method for selecting tokens when multiple tokens are provided in PIXIVFE_TOKEN.

Valid options:

• 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, reducing the risk of rate limiting for individual accounts by the Pixiv API.

Image proxy checker configuration

PixivFE includes a image proxy checker that periodically tests the pre-defined list of image proxy servers to determine which ones are working. It maintains an updated list of functional proxies that can be used to make image requests to Pixiv.

The following variables control the behavior of the proxy checker.

PIXIVFE_PROXY_CHECK_ENABLED

Config name: proxyCheckEnabled

Required: No

Default: true

Controls whether the image proxy checker is enabled. Set to false to completely disable proxy checking.

When disabled, PixivFE will not perform any checks on the image proxy servers, which can be useful in environments where this behavior is not needed or causes issues.

PIXIVFE_PROXY_CHECK_INTERVAL

Config name: proxyCheckInterval

Required: No

Default: 8h

The interval between proxy checks. Defaults to 8 hours if not set.

Please specify this value in Go's time.Duration notation, e.g. 2h3m5s.

You can disable periodic checks by setting the value to 0. Then, proxies will only be checked once at server initialization.

Token management configuration

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.

If not set, the default values will be used.

PIXIVFE_TOKEN_MAX_RETRIES

Config name: tokenMaxRetries

Required: No

Default: 5

Maximum number of retries for token management.

PIXIVFE_TOKEN_BASE_TIMEOUT

Config name: tokenBaseTimeout

Required: No

Default: 1000ms

Base timeout duration for token management.

PIXIVFE_TOKEN_MAX_BACKOFF_TIME

Config name: tokenMaxBackoffTime

Required: No

Default: 32000ms

Maximum backoff time for token management.

API response caching configuration

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 user's pixivfe-Token cookie.

PIXIVFE_CACHE_ENABLED

Config name: cacheEnabled

Required: No

Default: false

Controls whether the caching system is enabled. Set to true to enable caching. When disabled, all requests will be sent directly to the Pixiv API without caching.

Other caching configuration variables (PIXIVFE_CACHE_SIZE, PIXIVFE_CACHE_TTL, and PIXIVFE_CACHE_SHORT_TTL) will have no effect if this variable is set to false.

PIXIVFE_CACHE_SIZE

Config name: cacheSize

Required: No

Default: 100

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

Config name: cacheTTL

Required: No

Default: 60m

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.

PIXIVFE_CACHE_SHORT_TTL

Config name: cacheShortTTL

Required: No

Default: 10s

Specifies a shorter Time To Live (TTL) for specific API endpoints that change frequently. This shorter TTL is applied to the following paths:

• /ajax/discovery/artworks (used for the /discovery page)
• /ajax/discovery/novels (used for the /discovery/novels page)
• /ajax/illust/new (used for the /newest page)

These paths are considered more dynamic, and the shorter TTL ensures more up-to-date content.

HTTP caching configuration

These cache control settings affect browser-level caching behavior and are separate from PixivFE's internal API response cache. They help reduce server load by allowing browsers to cache artwork pages while ensuring content stays reasonably fresh.

PIXIVFE_CACHE_CONTROL_MAX_AGE

Config name: cacheControlMaxAge

Required: No

Default: 30s

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. The value should be specified in Go's time.Duration notation (e.g., 60s, 5m).

PIXIVFE_CACHE_CONTROL_STALE_WHILE_REVALIDATE

Config name: cacheControlStaleWhileRevalidate

Required: No

Default: 60s

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. The value should be specified in Go's time.Duration notation (e.g., 120s, 2m).

Feature configuration

PIXIVFE_POPULAR_SEARCH_ENABLED

Config name: popularSearchEnabled

Required: No

Default: false

Controls whether searching by popularity for a given tag is enabled.

Warning

This feature requires several API calls for each search, which may lead to rate limiting by the Pixiv API.

As such, enabling caching (PIXIVFE_CACHE_ENABLED=true) is recommended to minimize repeated requests.

Network proxy configuration

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 environment variable 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.

HTTPS_PROXY

Required: No

Proxy server used for requests made over HTTPS.

HTTP_PROXY

Required: No

Proxy server used for requests made over plain HTTP.

Development options

PIXIVFE_DEV

Config name: inDevelopment

Required: No

Set to any value to enable development mode, e.g., PIXIVFE_DEV=true. In development mode:

1. The server will live-reload HTML templates and SCSS files.
2. Caching is disabled.
3. Additional debug information is logged.
4. Responses are saved to PIXIVFE_RESPONSE_SAVE_LOCATION.

This setting is useful for developers working on PixivFE itself or for troubleshooting issues in a development environment.

PIXIVFE_RESPONSE_SAVE_LOCATION

Config name: responseSaveLocation

Required: No

Default: /tmp/pixivfe/responses

Defines where responses from the Pixiv API are saved when in development mode.

Logging Configuration

PixivFE uses uber-go/zap for structured, leveled logging. The following environment variables control the logging behavior.

PIXIVFE_LOG_LEVEL

Config name: logLevel

Required: No

Default: info

Sets the minimum level of log messages to output. Valid options are:

• 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

Config name: logOutputs

Required: No

Default: ["stdout"]

Specifies where log messages should be sent. This can be a single output or multiple outputs separated by commas. Valid options include:

• stdout: Standard output (console)
• stderr: Standard error
• File paths: e.g., /var/log/pixivfe.log

Example: PIXIVFE_LOG_OUTPUTS=stdout,/var/log/pixivfe.log

PIXIVFE_LOG_FORMAT

Config name: logFormat

Required: No

Default: console

Determines the format of log messages. Valid options are:

• console: Human-readable format suitable for console output
• json: Structured JSON format, useful for log parsing and analysis tools