Pip Installation

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

Install the package

pip3 install changedetection.io

Run the application

changedetection.io -d /path/to/empty/data/dir -p 5000

Access the web interface

Open your browser and navigate to:

http://127.0.0.1:5000

Installation Methods

pip3 install changedetection.io

python3 -m venv changedetection-env
source changedetection-env/bin/activate  # On Windows: changedetection-env\Scripts\activate
pip3 install changedetection.io

pip3 install --user 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

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

changedetection.io -d ./data -p 8080

changedetection.io -d ./data -h 0.0.0.0 -p 5000

nohup changedetection.io -d /var/lib/changedetection -p 5000 > /var/log/changedetection.log 2>&1 &

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

pip3 install jq~=1.3

pip3 install jq~=1.3

# jq is not available via pip on Windows
# Download from https://stedolan.github.io/jq/download/

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

Stop the application

If running as a service:

sudo systemctl stop changedetection

Or kill the process if running in foreground.

Update the package

pip3 install --upgrade changedetection.io

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.

Get Started

Installation

Core Features

Content Extraction

Browser Integration

Configuration

Advanced

Requirements

Quick Start

Installation Methods

Command Line Options

Available Options

Examples

Optional Dependencies

Playwright for JavaScript Support

OpenCV for Fast Image Comparison

jq for Advanced JSON Processing

Environment Variables

Common Environment Variables

Running as a System Service

systemd (Linux)

Supervisor (Linux/Unix)

Updating

Troubleshooting

Command not found

Permission denied on datastore

Import errors or missing dependencies

Port already in use

Playwright installation fails

SSL/Certificate errors

Uninstalling

Next Steps

Windows Installation

Configuration

​Requirements

​Quick Start

​Installation Methods

​Command Line Options

​Available Options

​Examples

​Optional Dependencies

​Playwright for JavaScript Support

​OpenCV for Fast Image Comparison

​jq for Advanced JSON Processing

​Environment Variables

​Common Environment Variables

​Running as a System Service

​systemd (Linux)

​Supervisor (Linux/Unix)

​Updating

​Troubleshooting

​Command not found

​Permission denied on datastore

​Import errors or missing dependencies

​Port already in use

​Playwright installation fails

​SSL/Certificate errors

​Uninstalling

​Next Steps

Windows Installation

Configuration

Requirements

Quick Start

Installation Methods

Command Line Options

Available Options

Examples

Optional Dependencies

Playwright for JavaScript Support

OpenCV for Fast Image Comparison

jq for Advanced JSON Processing

Environment Variables

Common Environment Variables

Running as a System Service

systemd (Linux)

Supervisor (Linux/Unix)

Updating

Troubleshooting

Command not found

Permission denied on datastore

Import errors or missing dependencies

Port already in use

Playwright installation fails

SSL/Certificate errors

Uninstalling

Next Steps