Overview This guide will take you from zero to your first working monitor with notifications in just a few minutes. By the end, you’ll have changedetection.io monitoring a website and sending you alerts when changes occur.
Choose your path:
Managed service : Sign up at changedetection.io for instant access ($8.99/month)Self-hosted : Follow the installation steps below for the free, open-source version Installation Choose the installation method that works best for you:
Docker (Recommended)
Docker Compose
Python pip
The fastest way to get started with changedetection.io: docker run -d --restart always \ -p "127.0.0.1:5000:5000" \ -v datastore-volume:/datastore \ --name changedetection.io \ dgtlmoon/changedetection.io
Mac users : Use port 5050 instead to avoid conflicts with AirPlay:docker run -d --restart always -p "127.0.0.1:5050:5000" ...
For more control and easier configuration: # Clone the repository git clone https://github.com/dgtlmoon/changedetection.io.git cd changedetection.io # Start the service docker compose up -d
The docker-compose.yml file includes:
Main changedetection service
Optional browser automation (Playwright/Selenium)
Volume configuration
Environment variables
Install directly via pip: # Install pip3 install changedetection.io # Run (specify data directory and port) changedetection.io -d /path/to/datastore -p 5000
The data directory will store all your watches, history, and settings. Verify Installation Once running, access the web interface:
Open your browser
Navigate to http://127.0.0.1:5000 (or http://127.0.0.1:5050 on Mac)
First-time setup
You should see the changedetection.io dashboard. No registration required for self-hosted installations!
The default installation uses the :latest tag for stable releases. Use :dev for bleeding-edge features from the master branch.
Create Your First Watch Now let’s set up your first website monitor:
Add a new watch
Click the ”+ Watch” button or “Add” in the top navigation. Enter a URL to monitor, for example: https://example.com/products/special-item
Configure basic settings
On the watch edit page, you can configure: Essential Settings:
URL : The webpage to monitorTitle : A friendly name for this watch (optional, auto-detected from page title)Check Interval : How often to check for changes Quick Setup:
For your first watch, leave most settings at default and click “Save” .
Run first check
Back on the watch list:
Find your newly created watch
Click the “Check Now” button (play icon)
Wait a few seconds for the first check to complete
The first check establishes a baseline — future checks will compare against this snapshot.
View the results
Click on your watch to view:
Current snapshot of the page
Extracted content
Check history
Detected changes (none yet on first run)
Add Content Filtering Monitor only specific parts of a page to avoid false positives:
Edit your watch and add CSS selectors to the “CSS/JSONPath/JQ Filter” field: /* Monitor only price elements */ .price , .product-price /* Monitor main content */ main article /* Monitor specific ID */ #product-details
Use browser DevTools (F12) to inspect elements and copy selectors.
If you have Playwright enabled:
Enable JavaScript fetcher
In watch settings, set “Fetch Method” to use Playwright/browser steps.
Open Visual Selector
Click the “Visual Selector” tab in the watch editor.
Select elements
Click on page elements to highlight and select what you want to monitor. The tool will generate the appropriate selectors automatically.
Visual Selector requires a Playwright connection. Configure PLAYWRIGHT_DRIVER_URL in your environment or use the managed service.
For complex targeting, use XPath expressions: <!-- Monitor specific table cells --> //table[@class='pricing']//td[@class='price'] <!-- Monitor paragraphs containing specific text --> //p[contains(text(), 'In Stock')] <!-- Monitor elements with regex (LXML) --> //div[re:test(@class, 'product-.*')]
Set Up Notifications Get alerted when changes are detected:
Configure notification endpoint
Edit your watch and scroll to the “Notifications” section. Add one or more notification URLs using the Apprise format: # Discord discord://webhook_id/webhook_token # Slack slack://TokenA/TokenB/TokenC/ # Email (SMTP) mailto://user:[email protected] ?to [email protected] # Telegram tgram://bot_token/chat_id/ # Microsoft Teams msteams://TokenA/TokenB/TokenC/ # Custom webhook json://your-server.com/webhook
You can add multiple notification URLs (one per line) to send alerts to multiple services.
Customize notification content (optional)
Use Jinja2 templates to customize your alerts: Title: Price changed for {{watch.title|default(watch.url)}}
Body: {{watch_url}} had a change detected! Last checked: {{current_timestamp}} Changes: {{diff}}
Available variables:
{{watch_url}}: The monitored URL{{watch.title}}: Watch title{{diff}}: HTML/text diff of changes{{current_timestamp}}: Check timestamp{{preview_url}}: Link to view the change
Test notifications
Click “Send test notification” to verify your configuration before saving.
Trigger Detection Control when notifications are sent:
Trigger on Text
Block on Text
Ignore Text
Only get notified when specific text appears: In Stock Available Now Price: $99
Add these to the “Trigger/wait for text” field. Supports regex: Price: \$ [ 0-9 ] +\. [ 0-9 ] {2} ( Available | In Stock )
Prevent notifications if specific text is present: Out of Stock Sold Out Temporarily Unavailable
Add to “Block change detection if text matches” . Exclude dynamic content from change detection: Last updated: Copyright © View count:
Lines matching these patterns will be ignored during comparison. Advanced: Monitor Prices For product monitoring, use the specialized restock processor:
Enable restock mode
In watch settings, enable: “Re-stock & Price detection for single product pages”
Set price thresholds
Configure optional price alerts:
Above price : Alert if price exceeds this amountBelow price : Alert if price drops below this amountPercentage change : Alert on % price change
Monitor stock status
The processor automatically extracts:
Product price from meta tags
Stock availability status
Product name and details
View this data directly in the watch preview. The restock processor extracts pricing data from standard e-commerce meta tags (schema.org, Open Graph) found on most product pages.
Schedule Monitoring Control when checks run:
Check Interval
Time Scheduling
Set how often the page is checked:
Every 5 minutes (frequent)
Every hour (moderate)
Once per day (light monitoring)
Custom: Specify weeks, days, hours, minutes, seconds
Respect the target website’s resources. Avoid excessive checking that could be seen as abusive.
Limit checks to specific times: Example: Business hours only
Monday-Friday: 9:00 AM - 5:00 PM
Timezone: Your local timezone
Example: Foreign news at 9 AM
Daily: 9:00 AM
Timezone: Target country timezone
Use the “Schedule” section in watch settings with quick presets for business hours or weekends. Common Patterns
URL : https://company.com/careers CSS Filter : .job-listing, .career-opportunity Trigger Text : (Software|Engineer|Developer) Check Interval : Every 6 hours
URL : https://store.com/product/item-id Processor : Restock & Price detection Below Price : 99.99 Notification : discord://... Check Interval : Every 1 hour
URL : https://api.example.com/status Filter : jq:.status.health Trigger Text : "degraded|down" Notification : slack://... Check Interval : Every 5 minutes
URL : https://government.gov/announcements CSS Filter : #press-releases article Ignore Text : Last updated:, Copyright Check Interval : Every 3 hours Schedule : Business hours only
Next Steps
Visual Selector Learn to precisely target page elements
Browser Steps Automate login, clicks, and form fills
JSON Filtering Monitor and filter JSON API responses
Proxy Setup Route requests through proxies
Troubleshooting
Changes detected on every check
Problem : Dynamic content (timestamps, ads, counters) triggers false positives.Solutions :
Use CSS/XPath selectors to monitor only relevant content
Add dynamic text to the “Ignore text” field
Use the Visual Selector to exclude changing elements
Notifications not sending
Checklist :
Test notification URL using “Send test notification” button
Check notification URL format matches Apprise syntax
Verify network connectivity to notification service
Check changedetection.io logs for error messages
JavaScript-heavy sites not loading
Problem : Content loaded by JavaScript doesn’t appear.Solution : Enable Playwright fetcher:
Uncomment browser service in docker-compose.yml
Set PLAYWRIGHT_DRIVER_URL environment variable
Change watch fetch method to “Playwright Chrome/Javascript”
Port 5000 already in use (Mac)
Problem : macOS AirPlay uses port 5000.Solution : Use port 5050:docker run ... -p "127.0.0.1:5050:5000" ...
