> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/dgtlmoon/changedetection.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Install the package">
    ```bash theme={null}
    pip3 install changedetection.io
    ```
  </Step>

  <Step title="Run the application">
    ```bash theme={null}
    changedetection.io -d /path/to/empty/data/dir -p 5000
    ```
  </Step>

  <Step title="Access the web interface">
    Open your browser and navigate to:

    ```
    http://127.0.0.1:5000
    ```
  </Step>
</Steps>

## Installation Methods

<CodeGroup>
  ```bash Global Installation theme={null}
  pip3 install changedetection.io
  ```

  ```bash Virtual Environment (Recommended) theme={null}
  python3 -m venv changedetection-env
  source changedetection-env/bin/activate  # On Windows: changedetection-env\Scripts\activate
  pip3 install changedetection.io
  ```

  ```bash User Installation theme={null}
  pip3 install --user changedetection.io
  ```
</CodeGroup>

<Note>
  Using a virtual environment is recommended to avoid conflicts with system packages.
</Note>

## Command Line Options

The `changedetection.io` command accepts several parameters:

```bash theme={null}
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

<CodeGroup>
  ```bash Basic Usage theme={null}
  changedetection.io -d /home/user/changedetection-data -p 5000
  ```

  ```bash Custom Port theme={null}
  changedetection.io -d ./data -p 8080
  ```

  ```bash Listen on All Interfaces theme={null}
  changedetection.io -d ./data -h 0.0.0.0 -p 5000
  ```

  ```bash Background Service theme={null}
  nohup changedetection.io -d /var/lib/changedetection -p 5000 > /var/log/changedetection.log 2>&1 &
  ```
</CodeGroup>

## Optional Dependencies

Some features require additional packages:

### Playwright for JavaScript Support

```bash theme={null}
pip3 install playwright~=1.56.0
playwright install chromium
```

<Note>
  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.
</Note>

### OpenCV for Fast Image Comparison

```bash theme={null}
pip3 install opencv-python-headless>=4.8.0.76
```

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

### jq for Advanced JSON Processing

<CodeGroup>
  ```bash Linux theme={null}
  pip3 install jq~=1.3
  ```

  ```bash macOS theme={null}
  pip3 install jq~=1.3
  ```

  ```bash Windows theme={null}
  # jq is not available via pip on Windows
  # Download from https://stedolan.github.io/jq/download/
  ```
</CodeGroup>

## Environment Variables

Configure the application using environment variables:

```bash theme={null}
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`:

```ini /etc/systemd/system/changedetection.service theme={null}
[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:

```bash theme={null}
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`:

```ini /etc/supervisor/conf.d/changedetection.conf theme={null}
[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:

```bash theme={null}
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start changedetection
```

## Updating

<Steps>
  <Step title="Stop the application">
    If running as a service:

    ```bash theme={null}
    sudo systemctl stop changedetection
    ```

    Or kill the process if running in foreground.
  </Step>

  <Step title="Update the package">
    ```bash theme={null}
    pip3 install --upgrade changedetection.io
    ```
  </Step>

  <Step title="Restart the application">
    If running as a service:

    ```bash theme={null}
    sudo systemctl start changedetection
    ```

    Or start manually:

    ```bash theme={null}
    changedetection.io -d /path/to/datastore -p 5000
    ```
  </Step>
</Steps>

## Troubleshooting

### Command not found

If `changedetection.io` is not in your PATH:

```bash theme={null}
# 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:

```bash theme={null}
mkdir -p /path/to/datastore
chmod 755 /path/to/datastore
```

### Import errors or missing dependencies

Reinstall with all dependencies:

```bash theme={null}
pip3 install --upgrade --force-reinstall changedetection.io
```

### Port already in use

Find and kill the process using the port:

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
pip3 uninstall changedetection.io
```

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Windows Installation" icon="windows" href="/installation/windows">
    Special instructions for Windows
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/environment-variables">
    Configure notifications and features
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.