Environment Variables

Configure changedetection.io using environment variables. Set these in your Docker Compose file, shell environment, or container orchestration platform.

Server Configuration

PORT

integer

default:"5000"

HTTP server listening portExample:

environment:
  - PORT=8080

Can also be set with the -p command-line option.

LISTEN_HOST

string

default:"0.0.0.0"

Host address to bind the server toValues:

0.0.0.0 - Listen on all IPv4 interfaces (default)
:: - Listen on all IPv6 interfaces
127.0.0.1 - Localhost only (more secure)

Example:

environment:
  - LISTEN_HOST=127.0.0.1

Can also be set with the -h command-line option.

BASE_URL

string

Base URL of your changedetection.io installationImportant: Required for notification links to work correctlyExample:

environment:
  - BASE_URL=https://changedetection.example.com

Used in notification templates as {{ base_url }}.

USE_X_SETTINGS

boolean

default:"false"

Enable proxy_pass/reverse proxy header supportWhen enabled, respects these headers:

X-Forwarded-For - Client IP
X-Forwarded-Proto - Original protocol (http/https)
X-Forwarded-Host - Original hostname
X-Forwarded-Port - Original port
X-Forwarded-Prefix - URL prefix (e.g., /app)

Example Nginx configuration:

location /app/ {
    proxy_pass http://changedetection:5000/;
    proxy_set_header Host "localhost";
    proxy_set_header X-Forwarded-Prefix /app;
}

Docker Compose:

environment:
  - USE_X_SETTINGS=1

See Running behind a reverse proxy for more details.

SSL/TLS Configuration

SSL_CERT_FILE

string

default:"cert.pem"

Path to SSL certificate fileExample:

environment:
  - SSL_CERT_FILE=/app/ssl/cert.pem
volumes:
  - ./ssl/cert.pem:/app/ssl/cert.pem

Enables HTTPS mode when both SSL_CERT_FILE and SSL_PRIVKEY_FILE are set.

SSL_PRIVKEY_FILE

string

default:"privkey.pem"

Path to SSL private key fileExample:

environment:
  - SSL_PRIVKEY_FILE=/app/ssl/privkey.pem
volumes:
  - ./ssl/privkey.pem:/app/ssl/privkey.pem

Logging Configuration

LOGGER_LEVEL

string

default:"DEBUG"

Log verbosity levelValues (most to least verbose):

TRACE - Most detailed, includes all internal operations
DEBUG - Detailed debugging information (default)
INFO - General informational messages
SUCCESS - Success confirmations only
WARNING - Warning messages
ERROR - Error messages
CRITICAL - Critical errors only

Example:

environment:
  - LOGGER_LEVEL=INFO

Can also be set with the -l command-line option.

Browser Configuration

PLAYWRIGHT_DRIVER_URL

string

Playwright/Chrome browser service URLFormat: ws://hostname:port or wss://hostname:portExample with Sockpuppetbrowser:

services:
  changedetection:
    environment:
      - PLAYWRIGHT_DRIVER_URL=ws://browser-sockpuppet-chrome:3000
  
  browser-sockpuppet-chrome:
    image: dgtlmoon/sockpuppetbrowser:latest
    cap_add:
      - SYS_ADMIN

Recommended: Use Sockpuppetbrowser for best performance and screenshot support.

WEBDRIVER_URL

string

WebDriver/Selenium URL (deprecated, use Playwright instead)Format: http://hostname:port/wd/hubExample:

environment:
  - WEBDRIVER_URL=http://browser-selenium-chrome:4444/wd/hub

WebDriver is deprecated. Does not support full-page screenshots or proper status code reporting. Use PLAYWRIGHT_DRIVER_URL instead.

Proxy Configuration

HTTP_PROXY

string

HTTP proxy for non-SSL requestsFormats:

http://proxy.example.com:8080
socks5://proxy.example.com:1080
socks5://user:pass@proxy.example.com:1080
socks5h://proxy.example.com:1080 (DNS through proxy)

Example:

environment:
  - HTTP_PROXY=socks5h://10.10.1.10:1080

HTTPS_PROXY

string

HTTPS proxy for SSL requestsFormats: Same as HTTP_PROXYExample:

environment:
  - HTTPS_PROXY=socks5h://10.10.1.10:1080

NO_PROXY

string

Comma-separated list of hosts to exclude from proxyingExample:

environment:
  - NO_PROXY="localhost,192.168.0.0/24,*.internal.com"

Common use: Exclude notification services from proxying to avoid rate limits.

Performance Configuration

FETCH_WORKERS

integer

default:"10"

Number of concurrent fetcher workersExample:

environment:
  - FETCH_WORKERS=20

Recommendations:

Increase for faster parallel checking (more CPU/memory)
Decrease for resource-constrained environments
Default of 10 works well for most setups

MINIMUM_SECONDS_RECHECK_TIME

integer

default:"3"

Absolute minimum seconds between rechecksExample:

environment:
  - MINIMUM_SECONDS_RECHECK_TIME=60

Overrides any watch-level minimum. Set to 0 to disable.

REQUESTS_RETRY_MAX_COUNT

integer

default:"6"

Maximum retry attempts for network requestsExample:

environment:
  - REQUESTS_RETRY_MAX_COUNT=3

Retries on connection timeouts, read timeouts, and connection resets (not HTTP status codes).

Screenshot Configuration

SCREENSHOT_MAX_HEIGHT

integer

default:"16000"

Maximum screenshot height in pixelsExample:

environment:
  - SCREENSHOT_MAX_HEIGHT=32000

Warning: Higher values increase RAM usage significantly.

SCREENSHOT_QUALITY

integer

default:"72"

JPEG screenshot quality (1-100)Example:

environment:
  - SCREENSHOT_QUALITY=90

Higher quality = larger files. PNG screenshots always use quality 100.

Security Configuration

HIDE_REFERER

boolean

default:"false"

Hide Referer header when users click outgoing linksExample:

environment:
  - HIDE_REFERER=true

Sets Referrer-Policy: same-origin to prevent monitored websites from seeing your changedetection.io hostname.

ALLOW_FILE_URI

boolean

default:"false"

Allow monitoring local files with file:// URIsExample:

environment:
  - ALLOW_FILE_URI=true
volumes:
  - /path/to/files:/files:ro

Security Warning: Only enable if you understand the security implications of allowing file system access.

ALLOW_IANA_RESTRICTED_ADDRESSES

boolean

default:"false"

Allow fetching from private/reserved IP addressesExample:

environment:
  - ALLOW_IANA_RESTRICTED_ADDRESSES=true

Security Warning: Enabling this allows SSRF attacks. Only enable in trusted networks.

Plugin Configuration

EXTRA_PACKAGES

string

Space-separated list of additional Python packages to installExample:

environment:
  - EXTRA_PACKAGES=changedetection.io-osint-processor another-plugin

See changedetection.io plugins for available plugins.

Privacy Configuration

DISABLE_VERSION_CHECK

boolean

default:"false"

Disable telemetry and version checkingExample:

environment:
  - DISABLE_VERSION_CHECK=true

For complete privacy if you don’t want to use the version check service.

Localization Configuration

string

Timezone for scheduling and timestampsFormat: TZ database nameExamples:

environment:
  - TZ=America/New_York
  - TZ=Europe/London
  - TZ=Asia/Tokyo

LC_ALL

string

default:"en_US.UTF-8"

Text processing localeExample:

environment:
  - LC_ALL=de_DE.UTF-8

UTF-8 should cover 99.99% of cases.

Testing Configuration

TESTING_SHUTDOWN_AFTER_DATASTORE_LOAD

boolean

default:"false"

Exit cleanly after datastore initialization (for CI/CD testing)Example:

environment:
  - TESTING_SHUTDOWN_AFTER_DATASTORE_LOAD=true

Used in automated upgrade tests.

Complete Docker Compose Example

services:
  changedetection:
    image: ghcr.io/dgtlmoon/changedetection.io
    container_name: changedetection
    hostname: changedetection
    
    environment:
      # Server Configuration
      - PORT=5000
      - LISTEN_HOST=0.0.0.0
      - BASE_URL=https://changedetection.example.com
      - USE_X_SETTINGS=1
      
      # Logging
      - LOGGER_LEVEL=INFO
      
      # Browser
      - PLAYWRIGHT_DRIVER_URL=ws://browser-sockpuppet-chrome:3000
      
      # Proxy
      - HTTP_PROXY=socks5h://10.10.1.10:1080
      - HTTPS_PROXY=socks5h://10.10.1.10:1080
      - NO_PROXY="localhost,192.168.0.0/24"
      
      # Performance
      - FETCH_WORKERS=10
      - MINIMUM_SECONDS_RECHECK_TIME=3
      
      # Screenshots
      - SCREENSHOT_MAX_HEIGHT=16000
      - SCREENSHOT_QUALITY=72
      
      # Security
      - HIDE_REFERER=true
      
      # Plugins
      - EXTRA_PACKAGES=changedetection.io-osint-processor
      
      # Privacy
      - DISABLE_VERSION_CHECK=false
      
      # Localization
      - TZ=America/Los_Angeles
      - LC_ALL=en_US.UTF-8
    
    volumes:
      - changedetection-data:/datastore
      - ./proxies.json:/datastore/proxies.json
    
    ports:
      - 127.0.0.1:5000:5000
    
    restart: unless-stopped
    
    depends_on:
      - browser-sockpuppet-chrome
  
  browser-sockpuppet-chrome:
    hostname: browser-sockpuppet-chrome
    image: dgtlmoon/sockpuppetbrowser:latest
    cap_add:
      - SYS_ADMIN
    restart: unless-stopped
    environment:
      - SCREEN_WIDTH=1920
      - SCREEN_HEIGHT=1024
      - SCREEN_DEPTH=16
      - MAX_CONCURRENT_CHROME_PROCESSES=10

volumes:
  changedetection-data:

Command-Line Options

Some settings can also be configured via command-line arguments:

changedetection.py [options]

Options:
  -s              SSL enable
  -h HOST         Listen host (default: 0.0.0.0)
  -p PORT         Listen port (default: 5000)
  -d PATH         Datastore path
  -l LEVEL        Log level (TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL)
  -c              Cleanup unused snapshots
  -C              Create datastore directory if it doesn't exist
  -P true/false   Set all watches paused (true) or active (false)
  -u URL          Add URL to watch (can be used multiple times)
  -u0 'JSON'      Set options for first -u URL
  -r all          Queue all watches for recheck on startup
  -r UUID,...     Queue specific watches (comma-separated UUIDs)
  -b              Batch mode (process queue then exit)

Example:

changedetection.py -h 127.0.0.1 -p 8080 -l INFO -d /data

Environment Variable Priority

When both environment variables and command-line options are set:

Command-line options take highest priority
Environment variables are used if no CLI option is set
Default values are used if neither is set

Example:

# PORT=8080 set in environment
changedetection.py -p 9000  # Uses port 9000 (CLI overrides env)

Troubleshooting

Variables Not Taking Effect

Check Docker Compose syntax: Ensure proper YAML formatting
Restart container: docker compose restart changedetection
Check logs: docker logs changedetection for parsing errors
Verify environment: docker exec changedetection env | grep VARIABLE_NAME

SSL Not Working

Verify both SSL_CERT_FILE and SSL_PRIVKEY_FILE are set
Check certificate files are mounted correctly
Ensure files are readable by the container user
Check logs for SSL initialization messages

Playwright Not Connecting

Verify PLAYWRIGHT_DRIVER_URL format: ws://hostname:port
Check browser container is running: docker ps
Test connectivity: docker exec changedetection curl -v ws://browser-sockpuppet-chrome:3000
Check firewall/network policies

Proxy Setup - Detailed proxy configuration
Notifications Setup - BASE_URL usage in notifications
Docker Compose Reference - Official docker-compose.yml

Get Started

Installation

Core Features

Content Extraction

Browser Integration

Configuration

Advanced

Server Configuration

SSL/TLS Configuration

Logging Configuration

Browser Configuration

Proxy Configuration

Performance Configuration

Screenshot Configuration

Security Configuration

Plugin Configuration

Privacy Configuration

Localization Configuration

Testing Configuration

Complete Docker Compose Example

Command-Line Options

Environment Variable Priority

Troubleshooting

Variables Not Taking Effect

SSL Not Working

Playwright Not Connecting

Get Started

Installation

Core Features

Content Extraction

Browser Integration

Configuration

Advanced

​Server Configuration

​SSL/TLS Configuration

​Logging Configuration

​Browser Configuration

​Proxy Configuration

​Performance Configuration

​Screenshot Configuration

​Security Configuration

​Plugin Configuration

​Privacy Configuration

​Localization Configuration

​Testing Configuration

​Complete Docker Compose Example

​Command-Line Options

​Environment Variable Priority

​Troubleshooting

​Variables Not Taking Effect

​SSL Not Working

​Playwright Not Connecting

​Related Documentation

Server Configuration

SSL/TLS Configuration

Logging Configuration

Browser Configuration

Proxy Configuration

Performance Configuration

Screenshot Configuration

Security Configuration

Plugin Configuration

Privacy Configuration

Localization Configuration

Testing Configuration

Complete Docker Compose Example

Command-Line Options

Environment Variable Priority

Troubleshooting

Variables Not Taking Effect

SSL Not Working

Playwright Not Connecting

Related Documentation