How to Use Changedetection.io: The Beginner's Guide (First Run, the Interval Lesson, First Watch, and the Browser-Steps Rule)

CodexFuse Team · 2026-11-01T02:44:12.590Z · 13 min read

Changedetection.io is the open-source self-hosted website change monitor. This beginner's guide covers the Docker install, first watch, the 3-hour interval lesson, visual selector, browser steps, price and restock tracking, Apprise notifications, JSON/PDF monitoring, and the datastore backup rule.

If you are tired of opening the same five tabs every morning to check whether a price dropped, a product came back in stock, or a page changed, learning how to use Changedetection.io ends that loop for good. Changedetection.io is a free, open-source website change monitoring tool: you give it a URL, tell it how often to look, and it alerts you the moment something changes — through email, Discord, Telegram, Gotify, and 80+ other notification channels. This changedetection.io tutorial for beginners runs the whole first arc in one guide: your first run, your first watch, the re-check interval lesson everyone gets wrong, the visual selector, filters, the browser-steps rule for login pages and cookie banners, the price and restock mode, notifications, JSON and PDF monitoring, and the backup rule that saves you on day two. If Docker is new to you, read our Docker beginner guide first — every serious Changedetection.io setup runs in a container.

What Is Changedetection.io?

Changedetection.io is an open-source, self-hosted tool that watches web pages and tells you when they change. It checks the pages you pick on a schedule you set, compares each new snapshot with the previous one, and sends you an alert only when something actually changed. The project is dgtlmoon/changedetection.io on GitHub — Apache-2.0 licensed, created in January 2021, with roughly 35,421 stars as of this writing and its latest release, 0.60.10, published October 26, 2026. The Docker Hub image has been pulled over 11.7 million times, and the repo is still pushed daily.

The design philosophy is "watch anything that can be fetched." It monitors plain web pages, JSON APIs (with JSONPath or jq filters), PDFs (tracking text changes, filesize, and checksums), and even builds RSS feeds out of changes in web content. There is no database to run — all data lives in JSON files inside a datastore directory you mount as a volume. That makes backups trivially simple, as you will see later.

What Do You Need Before You Install Changedetection.io?

You need a machine that runs Docker and about five minutes of attention. Most self-hosters run Changedetection.io on the same VPS that hosts their other apps; if you have not picked a server yet, our what is VPS hosting guide explains the whole landscape. The footprint is tiny: one NAS user tracked about 20 sites on a 6-minute interval at under 1% CPU and roughly 100 MB of RAM, per a community self-hosting writeup.

One decision to make up front: Docker Hub vs pip. The documented Docker path is the standard route — the official README's one-liner runs dgtlmoon/changedetection.io from Docker Hub, with ghcr.io/dgtlmoon/changedetection.io listed as an alternative mirror. A pip install exists (pip3 install changedetection.io) and works on a Raspberry Pi, but Docker keeps the data dir, updates, and backups in one tidy place. This guide uses Docker.

How Do You Install Changedetection.io with Docker?

You install Changedetection.io with a single docker run command, open port 5000, and you are in the dashboard. Here is the complete first-run arc, ten steps from zero to your first alert.

1. Run the container. Paste the official one-liner:

   docker run -d --restart always -p "127.0.0.1:5000:5000" -v datastore-volume:/datastore --name changedetection.io dgtlmoon/changedetection.io

   The -v datastore-volume:/datastore part is the important bit — it keeps all your watches in a named volume so they survive container updates.
2. Open the dashboard at http://YOUR_SERVER_IP:5000. There is no login by default on a local bind; add a password in Settings before you expose it to the internet.
3. Set your global re-check interval in Settings. The default is 3 hours. Change it later per-watch; the interval lesson below explains why you should think before you tighten it.
4. Add your first watch. Paste a URL in the "Add URL" field on the main page and click Watch. That is it — Changedetection.io takes its first snapshot immediately.
5. Pick the watch's interval. Open the watch's Edit page and set "Time between re-checks" — global default or a per-watch override.
6. Trim the noise with a filter. Use the Visual Selector (needs the Playwright fetcher, covered below) or a CSS/XPath filter to watch only the part of the page you care about.
7. Add a notification URL under Settings > Notifications — for example gotify://your-server/ with your Gotify token, or ntfy://your-topic. Changedetection.io speaks 80+ channels through the Apprise library. Our ntfy beginner guide pairs well here.
8. Send a test notification from the same page. Do this now, not at 2 a.m. when a restock lands.
9. Enable the price mode if you are tracking prices. In the watch's Edit page, turn on "Re-stock & Price detection" and set your upper and lower thresholds.
10. Set up your backup (one command, covered in the backup section). Then stop refreshing tabs manually.

If you manage several stacks through a UI instead of the command line, our Portainer beginner guide shows the same container as a clickable stack.

How Do the Re-Check Intervals Work?

Every watch re-checks on an interval that defaults to 3 hours globally and can be overridden per watch. The default comes straight from the source: the app's global default is time_between_check of 3 hours, and each watch can flip a flag to use its own schedule instead. For price drops and restocks, people tighten specific watches to minutes — the XDA TrueNAS writeup suggests 5-minute re-checks for restock urgency, and a NAS user ran ~20 sites on a 6-minute cycle.

The interval lesson is the politeness rule: aggressive intervals get your IP rate-limited or blocked by the site you are watching. One guide's "5-minute-vs-resources" math shows the temptation clearly — checking a page every 5 minutes is 288 requests a day from your IP. Set the global interval wide (the 3-hour default is sane), then tighten only the watches where speed actually matters, like restocks. There is also a floor: the MINIMUM_SECONDS_RECHECK_TIME setting defaults to 3 seconds as flood protection, overriding any watch or global setting that goes below it.

How Do You Add Your First Watch?

You add a watch by pasting a URL on the main page and clicking Watch — Changedetection.io snapshots the page immediately. The watch then lives in your watch list with its status, last check time, and a diff link. Open Edit on any watch to reach the real controls: re-check interval, filters, triggers, notification overrides, and the browser-steps tab.

Two kinds of "first watch" cover most beginners. The simple kind: a static page where the text you care about is in the HTML — paste the URL, watch it, filter the noise. The tricky kind: a page that needs JavaScript to render, a login, or a cookie click — that one needs the Playwright fetcher and possibly browser steps, covered next.

How Does the Visual Selector Work?

The visual selector lets you point and click on the part of the page you want to watch, and Changedetection.io builds the CSS or XPath filter for you. This is visual website monitoring without writing selectors: open the watch, go to the Visual Selector tab, click the price box or the "In stock" line, and from then on only that element triggers alerts. Header banners, ad rotations, and daily widgets stop waking you up.

There is one requirement: the visual selector needs the Playwright content fetcher connected, because the point-and-click interface works on a rendered page. Once Playwright is enabled, pair the selector with the Filters & Triggers tab — "remove elements" strips noisy blocks, "ignore text" skips volatile strings, and "trigger/wait for text" only fires when your keyword appears or disappears.

When Do You Need Browser Steps?

You need browser steps when the page you want to watch requires interaction first: logging in, clicking "accept cookies", filling a search box, adding to cart, or picking a date. Browser steps record that sequence — type in the text boxes, click the buttons — and Changedetection.io replays it with Playwright before every check, then reads the resulting page.

The changedetection.io browser steps rule is simple: no Playwright, no browser steps. The compose file from the official docs ships a playwright-chrome service you uncomment via the PLAYWRIGHT_DRIVER_URL variable; a community writeup runs it as ws://playwright-chrome:3000. One honest warning from the XDA piece: by default no JavaScript content is loaded at all, so any JS-heavy page watches garbage until you attach the Chrome server. Plan for the extra container from the start if you watch modern single-page apps or price pages.

How Do You Track Prices and Restocks?

You track prices by enabling "Re-stock & Price detection" on a single product page's watch — the price drop tracker self hosted setup thousands of people run. Changedetection.io extracts the product's HTML metadata, tracks the price over time as a graph, and alerts on upper, lower, or percentage thresholds you define. The TrueNAS community writeup is the canonical price arc: deploy via compose with the Chrome server container (JS pages need it), set a 5-minute interval on the product watch, and add an Apprise notification URL.

Restock alerts use the same machinery with a different trigger. Watch the product page, filter down to the stock-status element with the visual selector, and set "trigger/wait for text" on the "out of stock" string — the alert fires when the text changes, i.e., when it comes back. Keep the politeness lesson from the interval section in mind: 5-minute checks on a retailer's page are a lot of requests, and retailers rate-limit aggressively.

How Do You Set Up Notifications in Changedetection.io?

You set up changedetection.io notifications by pasting an Apprise URL into the Notification URL list, globally or per watch. Changedetection.io does not build a separate integration for every chat app — it embeds the Apprise library, which speaks 80+ services (the project's own Docker Hub description says "85+ more") through URL-shaped configs. Title and body support Jinja2 templating when you want custom formatting.

Set global URLs in Settings > Notifications and per-watch URLs in the watch's Edit page — a price watch can ping Telegram instantly while a compliance watch emails a daily digest. Always hit "Send test notification" after adding a URL. The Make.com community tutorial shows the same mechanism driving webhooks into automation platforms: paste your webhook URL as the notification target and every change becomes an event in your pipeline.

Can Changedetection.io Monitor JSON APIs and PDFs?

Yes — Changedetection.io monitors JSON APIs with JSONPath or jq filters and PDFs by tracking text changes, filesize, and checksums. Paste an API endpoint as the watch URL and add a JSONPath filter like $.price so only the field you care about triggers alerts. JSON embedded inside HTML pages can be filtered the same way.

PDF monitoring covers a quiet but valuable niche: contracts, price lists, manuals, and reports published as files. Changedetection.io watches the file's text, its size, and its checksum, and the latest releases even keep the original PDF of the two newest versions so you can diff them. Developers get a bonus: a full REST API with interactive docs and an OpenAPI spec, plus an official Chrome extension that pushes your current tab straight into your install.

How Do You Back Up Changedetection.io?

You back up Changedetection.io by copying the datastore directory — there is no database to dump. Every watch, snapshot, and setting lives as JSON files under /datastore (or whatever you mounted as -v datastore-volume:/datastore). The community NAS writeup mounts /config to a local NAS folder precisely so the backup is a folder copy, and the project wiki has a dedicated "Restoring backup files" page.

Make this a habit before you accumulate 50 watches. A named volume plus a nightly docker cp or a host bind-mount with your normal backup tool is enough. Losing the datastore means re-adding every URL and re-learning every interval — a five-second backup prevents a lost afternoon.

What Is the Self-Hosted vs Cloud Decision?

The project offers a hosted cloud plan at $8.99/month with unlimited checks and watches plus a Chrome browser included, or you self-host for free and own everything. Self-hosting wins when the URL list is sensitive — competitor prices, compliance pages, client sites — because the watched URLs never leave your server. The cloud plan wins when you want zero maintenance and the hosted Chrome browser for JS-heavy pages.

Cost math favors self-hosting hard: the same VPS that runs your other containers absorbs Changedetection.io for essentially zero marginal cost (remember the <1% CPU, ~100 MB RAM community figure). One caveat if you expose it: put it behind HTTPS and set a password. Our Caddy beginner guide is the fastest way to get a TLS-terminated reverse proxy in front of it.

What Are the Common Beginner Mistakes?

Most beginners stumble on the same five things. The table below is the shortcut version of everything above.

Sources

Changedetection.io GitHub repository (dgtlmoon/changedetection.io) — project description, 35,421 stars, Apache-2.0 license, created 2021-01-27, last pushed October 31, 2026; latest release 0.60.10 (October 26, 2026); Docker one-liner, default port 5000, pip install instructions, datastore/JSON storage, browser steps, visual selector, Playwright fetcher, Apprise notifications, price/restock mode, JSONPath/jq filters, PDF monitoring, RSS of changes, REST API, Chrome extension, hosted plan $8.99/month. (github.com/dgtlmoon/changedetection.io, fetched 2026-11-01) · App model source confirming the 3-hour global default re-check interval and per-watch override flag; Misc system settings wiki page confirming MINIMUM_SECONDS_RECHECK_TIME default 3 seconds. (raw.githubusercontent.com, fetched 2026-11-01) · Docker Hub dgtlmoon/changedetection.io — 11,770,755 pulls, "85+ more" notification channels, tag conventions. (hub.docker.com, fetched 2026-11-01) · Playwright content fetcher wiki — PLAYWRIGHT_DRIVER_URL, playwright-chrome compose service, sockpuppetbrowser image. (github.com/dgtlmoon/changedetection.io/wiki, fetched 2026-11-01) · DarkWebInformer changedetection.io overview — capability tour: visual selector, 80+ channels, JSON API, PDF change detection. (darkwebinformer.com, fetched 2026-11-01) · XDA Developers TrueNAS guide — default no-JS rendering, Chrome server container, 5-minute restock interval suggestion, Apprise notification URLs. (xda-developers.com, fetched 2026-11-01) · Jussi Roine self-hosting writeup — linuxserver image on Synology NAS, port 5000→5002, /config backup mount, <1% CPU, ~100 MB RAM, ~20 sites at 6-minute intervals. (jussiroine.com, fetched 2026-11-01)

Frequently Asked Questions

Is Changedetection.io really free?

Yes. The self-hosted version is Apache-2.0 open source and free forever — the Docker image, the pip package, all features. The project also sells a hosted cloud plan at $8.99/month if you would rather not run a server, but nothing in the self-hosted version is paywalled.

How often should I set the re-check interval?

Keep the 3-hour global default for ordinary watches and tighten only the ones where minutes matter, like restocks. Aggressive intervals get your IP rate-limited by the site you are watching, so 5-minute checks belong on a handful of product pages, not your whole watch list.

Do I need Playwright to use Changedetection.io?

Only for JavaScript-rendered pages, the visual selector, and browser steps. Plain static pages work with the default fetcher. But modern sites are mostly JavaScript, so attach the playwright-chrome service early — without it, snapshots of JS pages come back empty.

What notifications does Changedetection.io support?

Over 80, through the embedded Apprise library: Gotify, ntfy, email, Discord, Telegram, Slack, Matrix, webhooks, and dozens more. You configure them as Apprise URLs globally or per watch, with Jinja2 templates for custom title and body formatting.

Can Changedetection.io watch pages behind a login?

Yes, with browser steps plus Playwright. Record the login sequence once — type credentials, click submit, dismiss the cookie banner — and Changedetection.io replays it before every check. Only monitor pages you are allowed to watch, and respect each site's terms of service.