---
name: "urlwatch-config"
section: "5"
platform: "linux"
package: "urlwatch"
version: "2.29-4"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/urlwatch-config"
---

# urlwatch-config(5)

Configuration of urlwatch behavior

## NAME

urlwatch-config - Configuration of urlwatch behavior

## SYNOPSIS

urlwatch --edit-config

## DESCRIPTION

The global configuration for urlwatch contains basic settings for the generic behavior of urlwatch as well as the *Reporters*.

## DISPLAY

In addition to always reporting changes (which is the whole point of urlwatch), urlwatch by default reports newly-added (**new**) pages and errors (**error**). You can change this behavior in the **display** section of the configuration:

```
display:
  new: true
  error: true
  unchanged: false
  empty-diff: true
```

If you set **unchanged** to **true**, urlwatch will always report all pages that are checked but have not changed.

The **empty-diff** settings control what happens if a page is **changed**, but due to e.g. a **diff\_filter** the diff is reduced to the empty string. If set to **true**, urlwatch will report an (empty) change. If set to **false**, the change will not be included in the report.

### Filter changes are not applied for unchanged

Due to the way the filtered output is stored, **unchanged** will always report the old contents with the filters at the time of retrieval, meaning that any changes you do to the **filter** of a job will not be visible in the **unchanged** report. When the page changes, the new filter will be applied.

For this reason, **unchanged** cannot be used to test filters, you should use the **--test-filter** command line option to apply your current filter to the current page contents.

## REPORTERS

"Reporters" are the modules that deliver notifications through their respective medium when they are enabled through the configuration file.

See **[urlwatch-reporters(5)](/urlwatch-reporters/5.md)** for reporter-specific options.

In addition to the reporter-specific options, all reporters support these options:

- •

  **enabled**: *\[bool\]* Activate the reporter. (default: False)

- •

  **separate**: *\[bool\]* Send a report for each job rather than a combined report for all jobs. (default: False)

Reporters are implemented in a hierarchy, such that these common configuration settings will apply to all descendent reporters:

```
html
text
├───stdout
├───email
├───ifttt
├───webservice
│   ├───pushover
│   └───pushbullet
├───mailgun
├───telegram
├───slack
│   └───mattermost
├───discord
├───xmpp
├───prowl
└───shell
markdown
├───matrix
└───gotify
```

**NOTE:**

Setting the *email* reporter's *html* option to *true* will cause it to inherit from the *html* configuration.

Here is an example configuration that reports on standard output in color, as well as HTML e-mail using **sendmail**:

```
report:
  text:
    details: true
    footer: true
    line_length: 75
  html:
    diff: unified
    separate: true
  email:
    enabled: true
    method: sendmail
    sendmail:
        path: /usr/sbin/sendmail
    from: 'urlwatch@example.org'
    to: 'you@example.org'
    html: true
    subject: '{count} changes: {jobs}'
  stdout:
    color: true
    enabled: true
```

Any reporter-specific configuration must be below the **report** key in the configuration.

## JOB DEFAULTS

If you want to change some settings for all your jobs, edit the **job\_defaults** section in your config file:

```
job_defaults:
  all:
    diff_tool: wdiff
  url:
    ignore_connection_errors: true
```

The above config file sets all jobs to use **wdiff** as diff tool, and all **url** jobs to ignore connection errors.

The possible sub-keys to **job\_defaults** are:

- •

  **all**: Applies to all your jobs, independent of its kind

- •

  **shell**: Applies only to **shell** jobs (with key **command**)

- •

  **url**: Applies only to **url** jobs (with key **url**)

- •

  **browser**: Applies only to **browser** jobs (with key **navigate**)

See *Jobs* about the different job kinds and what the possible keys are.

## FILES

**$XDG\_CONFIG\_HOME/urlwatch/urlwatch.yaml**

## SEE ALSO

**[urlwatch(1)](/urlwatch/1.md)**, **[urlwatch-reporters(5)](/urlwatch-reporters/5.md)**, **[urlwatch-intro(7)](/urlwatch-intro/7.md)**, **[urlwatch-cookbook(7)](/urlwatch-cookbook/7.md)**

## COPYRIGHT

2024 Thomas Perl