Environment Variables

The Apprise API container is highly configurable via environment variables.

Runtime Configuration

Variable	Default	Description
APPRISE_STATEFUL_MODE	hash	Controls the persistent storage backend. simple: Saves configs as human-readable files (/config/{KEY}.yaml). Recommended for most users. hash: Saves configs as indexed hashes. Efficient for high-volume. disabled: Disables persistent storage entirely (Stateless only).
APPRISE_WORKER_COUNT	(Auto)	Number of Gunicorn workers. Defaults to (2 * CPUs) + 1. Set to 1 for low-resource environments.
APPRISE_WORKER_MAX_REQUESTS	1000	Number of requests a worker handles before being recycled. Recycling releases accumulated memory. Lower this (e.g., 100) if workers are long-lived and memory growth is a concern.
APPRISE_WORKER_MAX_REQUESTS_JITTER	50	Random offset added to APPRISE_WORKER_MAX_REQUESTS to stagger worker restarts and avoid a thundering herd.
APPRISE_WORKER_TIMEOUT	300	Worker timeout in seconds.
APPRISE_BASE_URL	(None)	Set this if running behind a reverse proxy under a subpath (e.g., /apprise).
APPRISE_ADMIN	no	Set to yes to enable the /cfg endpoint, allowing you to list all saved keys in the Web UI. This ONLY works however if APPRISE_STATEFUL_MODE is set to simple.

Security & Access

Variable	Default	Description
APPRISE_CONFIG_LOCK	no	Set to yes to make the configuration read-only. Prevents adding or modifying keys via API.
ALLOWED_HOSTS	*	Space-delimited list of allowed Host headers.
APPRISE_DENY_SERVICES	(Default List)	Comma-separated list of schemas to block (e.g., dbus, windows, macosx, gnome, syslog are blocked by default in Docker).
APPRISE_ALLOW_SERVICES	(All)	Comma-separated list of allowed schemas. If set, only these services will work.

Memory Impact of Service Filtering

APPRISE_ALLOW_SERVICES and APPRISE_DENY_SERVICES do more than toggle which schemas are active. The Apprise API automatically evicts optional libraries from memory when every plugin that depends on them is disabled.

Each notification plugin that requires a heavy optional dependency declares it internally. When the last plugin using a given library is disabled, that library is removed from the Python runtime (sys.modules), freeing its associated objects. This happens at startup, before the first request is served.

The libraries subject to eviction and their estimated savings:

Library	Used By	Freed Memory
slixmpp	xmpp://	~20 MB
paho	mqtt://	~4 MB
gntp	growl://	~2 MB
smpplib	smpp://, smpps://	~2 MB
hid	blink1://	~2 MB
pgpy	mailto://, mailtos:// (PGP only)	~10 MB
cryptography	simplepush://, fcm://, vapid://	partial†

†cryptography links against OpenSSL natively. The Python wrapper objects are released, but the underlying shared library remains mapped by the OS for the process lifetime.

Example — a deployment that only needs Telegram and NTFY:

APPRISE_ALLOW_SERVICES=tgram,ntfy

This disables every other plugin, causing slixmpp, paho, gntp, smpplib, and the cryptography wrappers to be evicted. Combined with APPRISE_WORKER_COUNT=1, this brings a single-worker container from the typical ~180 MB baseline down to approximately ~145 MB.

Note

This eviction behaviour is specific to the Apprise API. The Apprise Python library used directly or embedded in third-party projects does not evict libraries — disabled plugins simply become inactive, leaving all loaded modules intact.

For a full guide on reducing container memory and RAM usage, see Resource Usage.

Storage & Limits

Variable	Default	Description
APPRISE_ATTACH_SIZE	200	Maximum attachment size in MB. Set to 0 to disable attachments.
APPRISE_UPLOAD_MAX_MEMORY_SIZE	3	Maximum size (MB) of request body kept in memory before spilling to disk.
APPRISE_CONFIG_MAX_LENGTH	512	Maximum configuration payload size in KB. Cannot exceed APPRISE_UPLOAD_MAX_MEMORY_SIZE.
APPRISE_RECURSION_MAX	1	Max recursion depth for apprise:// calls to other servers.

Network

Variable	Default	Description
HTTP_PORT	8000	Internal container port.
PUID	1000	User ID to run the service as.
PGID	1000	Group ID to run the service as.
IPV4_ONLY	no	Force IPv4 only.
IPV6_ONLY	no	Force IPv6 only.

Additional Apprise API Settings

The container also supports the following variables, which map directly to the server settings.

About <BASE_DIR> in default values

<BASE_DIR> is not an environment variable — it refers to the directory where the Apprise API application is installed and running from (its working directory). Relative paths you set for any of these variables are also resolved from that same directory. If you need to store data outside the install directory, use an absolute path (e.g. /data/apprise/config).

Variable	Default	Description
APPRISE_DEFAULT_CONFIG_ID	apprise	Default configuration key used by the web UI.
APPRISE_WEBHOOK_URL	(Empty)	Optional webhook that receives a POST payload after each notification attempt.
APPRISE_CONFIG_DIR	<BASE_DIR>/var/config	Directory storing configurations. Relative to <BASE_DIR> unless an absolute path is given.
APPRISE_STORAGE_DIR	<APPRISE_CONFIG_DIR>/store	Directory storing persistent storage.
APPRISE_STORAGE_MODE	auto	Persistent storage mode. Values: memory, auto, flush.
APPRISE_STORAGE_PRUNE_DAYS	30	Number of days before persistent storage is pruned.
APPRISE_STORAGE_UID_LENGTH	8	Default URL id length used by persistent storage.
APPRISE_ATTACH_DIR	<BASE_DIR>/var/attach	Directory storing uploaded attachments. Relative to <BASE_DIR> unless an absolute path is given.
APPRISE_ATTACH_SIZE	200	Maximum attachment size in MB. Set to 0 to disable attachments.
APPRISE_CONFIG_MAX_LENGTH	512	Maximum configuration payload size in KB accepted by form and API configuration updates. Independent of the upload body limit. Cannot exceed APPRISE_UPLOAD_MAX_MEMORY_SIZE.
APPRISE_MAX_ATTACHMENTS	6	Maximum number of attachments per request. Set to 0 to disable the limit.
APPRISE_WEBHOOK_MAPPING_MAX_DEPTH	5	Maximum traversal depth for nested field mapping rules. Depth counts every individual step — each dict-key lookup and each array-index dereference ([N]). For example, items[0].objectURI is 3 steps and a[0][1][2].value[3] is 6 steps. See Payload Mapping Hooks.
APPRISE_ATTACH_ALLOW_URL	*	Allow list for remote attachment URLs.
APPRISE_ATTACH_REJECT_URL	127.0.* localhost*	Deny list for remote attachment URLs.
APPRISE_STATELESS_URLS	(Empty)	Default URLs used by stateless /notify/ requests when no urls are supplied.
APPRISE_STATELESS_STORAGE	no	Allow stateless requests to use persistent storage when enabled.
APPRISE_DENY_SERVICES	(Platform list)	Comma-separated list of schemas to disable.
APPRISE_ALLOW_SERVICES	(Empty)	Exclusive allow list. If set, anything not in this list is disabled.
APPRISE_PLUGIN_PATHS	<BASE_DIR>/var/plugin	Comma-separated list of plugin paths to scan. Relative to <BASE_DIR> unless absolute paths are given.
APPRISE_API_ONLY	no	Disable the web UI and allow only the API endpoints.
APPRISE_DEFAULT_THEME	light	Default theme for the web UI. Values: light, dark.
APPRISE_INTERPRET_EMOJIS	(Unset)	If set, overrides emoji interpretation. Values: yes or no.
APPRISE_HTTP_REDIRECTS	yes	By default, Apprise follows HTTP 3xx redirects, matching the behaviour of the underlying requests library. Set to no to disable redirect following globally across all plugins without touching individual URLs. Individual URLs can still override this with ?redirect=yes or ?redirect=no.

Django and Logging

Variable	Default	Description
SECRET_KEY	(Bundled default)	Django secret key. Always override this in production.
DEBUG	no	Enable debug mode. Supports yes, 1, true, and similar.
LOG_LEVEL	INFO	Log level for both Django and Apprise logs.
TZ	Etc/UTC	Timezone for all log timestamps. Accepts any IANA timezone name (e.g. America/New_York, Europe/London) — see the tz database time zones for valid values. Every process in the container (Python logging, nginx, etc.) inherits TZ directly, so timestamps are always consistent regardless of whether the container runs as root or non-root. Bind-mounting /etc/localtime or /etc/timezone without setting TZ is no longer supported — set TZ to the desired zone name instead.
ALLOWED_HOSTS	*	Space-delimited allowed host list.
APPRISE_UPLOAD_MAX_MEMORY_SIZE	3	Maximum request body size (MB) stored in memory before Django raises RequestDataTooBig.