Pip Installation

Install changedetection.io using Python pip

Install changedetection.io directly on your system using Python’s package manager. This method provides maximum flexibility and is ideal for development or custom deployments.

Requirements

• Python 3.10 or higher
• pip3 (Python package manager)
• Linux, macOS, or Windows (with additional setup)

Quick Start

1. Install the package

   pip3 install changedetection.io
   
2. Run the application

   changedetection.io -d /path/to/empty/data/dir -p 5000
   
3. Access the web interface

   Open your browser and navigate to:

   http://127.0.0.1:5000
   

Installation Methods

Global Installation

pip3 install changedetection.io

Using a virtual environment is recommended to avoid conflicts with system packages.

Command Line Options

The changedetection.io command accepts several parameters:

changedetection.io -d /path/to/datastore -p 5000 -h 0.0.0.0

Available Options

Option	Description	Default
-d, --datastore	Path to datastore directory (required)	-
-p, --port	Port for web interface	5000
-h, --host	Host address to bind to	127.0.0.1

Examples

Basic Usage

changedetection.io -d /home/user/changedetection-data -p 5000

Optional Dependencies

Some features require additional packages:

Playwright for JavaScript Support

pip3 install playwright~=1.56.0
playwright install chromium

Playwright is not available on all platforms (e.g., arm/v6, arm/v7, Alpine Linux). The application will run without it but won’t support JavaScript-heavy websites.

OpenCV for Fast Image Comparison

pip3 install opencv-python-headless>=4.8.0.76

OpenCV installation can take a long time on ARM platforms. The application uses pixelmatch as a fallback if OpenCV is not installed.

jq for Advanced JSON Processing

Linux

pip3 install jq~=1.3

Environment Variables

Configure the application using environment variables:

export PORT=5000
export LOGGER_LEVEL=INFO
export BASE_URL=https://example.com
export FETCH_WORKERS=10
changedetection.io -d ./data

Common Environment Variables

Variable	Default	Description
PORT	5000	Web interface port
LOGGER_LEVEL	DEBUG	TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL
BASE_URL	-	Base URL for notifications
FETCH_WORKERS	10	Number of concurrent fetchers
MINIMUM_SECONDS_RECHECK_TIME	3	Minimum recheck interval
TZ	System timezone	Timezone for scheduling
HTTP_PROXY	-	HTTP proxy URL
HTTPS_PROXY	-	HTTPS proxy URL
DISABLE_VERSION_CHECK	false	Disable version checking

Running as a System Service

systemd (Linux)

Create a service file at /etc/systemd/system/changedetection.service:

/etc/systemd/system/changedetection.service

[Unit]
Description=changedetection.io
After=network.target

[Service]
Type=simple
User=changedetection
WorkingDirectory=/var/lib/changedetection
ExecStart=/usr/local/bin/changedetection.io -d /var/lib/changedetection -p 5000
Restart=always
Environment="LOGGER_LEVEL=INFO"
Environment="FETCH_WORKERS=10"

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable changedetection
sudo systemctl start changedetection
sudo systemctl status changedetection

Supervisor (Linux/Unix)

Create a configuration file at /etc/supervisor/conf.d/changedetection.conf:

/etc/supervisor/conf.d/changedetection.conf

[program:changedetection]
command=/usr/local/bin/changedetection.io -d /var/lib/changedetection -p 5000
directory=/var/lib/changedetection
user=changedetection
autostart=true
autorestart=true
stdout_logfile=/var/log/changedetection.log
stderr_logfile=/var/log/changedetection.error.log
environment=LOGGER_LEVEL="INFO",FETCH_WORKERS="10"

Start the service:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start changedetection

Updating

1. Stop the application

   If running as a service:

   sudo systemctl stop changedetection
   

   Or kill the process if running in foreground.

2. Update the package

   pip3 install --upgrade changedetection.io
   
3. Restart the application

   If running as a service:

   sudo systemctl start changedetection
   

   Or start manually:

   changedetection.io -d /path/to/datastore -p 5000
   

Troubleshooting

Command not found

If changedetection.io is not in your PATH:

# Find the installation location
pip3 show changedetection.io

# Add to PATH (add to ~/.bashrc or ~/.zshrc for persistence)
export PATH="$HOME/.local/bin:$PATH"

# Or run directly
python3 -m changedetectionio -d ./data -p 5000

Permission denied on datastore

Ensure the datastore directory is writable:

mkdir -p /path/to/datastore
chmod 755 /path/to/datastore

Import errors or missing dependencies

Reinstall with all dependencies:

pip3 install --upgrade --force-reinstall changedetection.io

Port already in use

Find and kill the process using the port:

# Linux/Mac
lsof -i :5000
kill <PID>

# Or use a different port
changedetection.io -d ./data -p 8080

Playwright installation fails

Playwright has platform-specific limitations:

• Not available on Alpine Linux (musl)
• Not available on arm/v6 or arm/v7
• Requires system dependencies on some platforms

# Install system dependencies (Debian/Ubuntu)
sudo apt-get install libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 \
  libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 \
  libxfixes3 libxrandr2 libgbm1 libasound2

# Then install Playwright
pip3 install playwright~=1.56.0
playwright install chromium

SSL/Certificate errors

If you encounter SSL certificate errors when fetching pages:

# Update certificates (Debian/Ubuntu)
sudo apt-get update && sudo apt-get install ca-certificates

# Or set environment variable to use custom certificates
export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.crt

Uninstalling

Remove the package:

pip3 uninstall changedetection.io

This does not remove your datastore. Manually delete the datastore directory if you want to remove all data.

Next Steps

Windows Installation

Special instructions for Windows

Configuration

Configure notifications and features