Skip to main content
Version: Next 🚧

Container Labels

Container labels allow you to customize WUD behavior on a per-container basis by attaching wud.* labels directly to your Docker or Compose services.

Available Labels​

wud.display.icon
Optionalstringdefault: mdi:docker

Custom display icon for the container in the UI and integrations

Allowed values:Any Iconify icon (mdi, simple-icons, selfhst, logos, fa6, etc.)
wud.display.name
Optionalstringdefault: Container name

Custom display name for the container in notifications and UI

Allowed values:Any string
wud.link.template
Optionalenum

Browsable URL template for changelogs and release notes

Allowed values:JS string template (${container}, ${original}, ${transformed}, ${major}, ${minor}, ${patch}, ${prerelease})
wud.tag.exclude
Optionalregex

Regular expression matching image tags to ignore

Allowed values:Valid JavaScript RegExp
wud.tag.include
Optionalregex

Regular expression matching image tags to consider as update candidates

Allowed values:Valid JavaScript RegExp
wud.tag.transform
Optionalregex

Transform rule to extract clean semver versions from non-standard tags

Allowed values:`$regex => $string` with capturing groups
wud.trigger.exclude
Optionallist

List of triggers to exclude for this container

Allowed values:`trigger1,trigger2:threshold`
wud.trigger.include
Optionallist

List of triggers to include for this container

Allowed values:`trigger1,trigger2:threshold`
wud.watch
Optionalbooleandefault: true

Enable or disable monitoring for this container

Allowed values:Boolean (`true`, `false`)
wud.watch.digest
Optionalbooleandefault: false

Track digest changes on registry for mutable tags (e.g. latest)

Allowed values:Boolean (`true`, `false`)

Practical Examples​

1. Opt-in Monitoring (Monitor Only Selected Containers)​

Set WUD_WATCHER_{watcher_name}_WATCHBYDEFAULT=false in your WUD configuration:

services:
  whatsupdocker:
    image: getwud/wud
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - WUD_WATCHER_LOCAL_WATCHBYDEFAULT=false

Then add wud.watch=true only to the containers you want to monitor:

services:
  mariadb:
    image: mariadb:10.4.5
    labels:
      - wud.watch=true

2. Exclude Specific Containers​

When WATCHBYDEFAULT=true (the default), you can exclude specific containers with wud.watch=false:

services:
  legacy_app:
    image: myapp:1.0.0
    labels:
      - wud.watch=false

3. Filter Tags with Regular Expressions​

You can filter which tags are considered valid candidates for updates by specifying inclusion or exclusion regex patterns.

For example, to monitor only standard x.y.z 3-part semver tags (ignoring alpine, beta, etc.):

services:
  mariadb:
    image: mariadb:10.4.5
    labels:
      - wud.tag.include=^\d+\.\d+\.\d+$$

4. Transform Non-Standard Tags Before Semver Analysis​

In certain cases, image tags include metadata suffixes (such as commit hashes or build numbers) like 1.0.0-99-7b368146 or 1.0.0-273-21d7efa6.

By default, the trailing SHA-1 hash (-7b368146) interferes with comparison, even though 1.0.0-99 represents a valid semver version ($major.$minor.$patch-$prerelease).

Syntax​

$valid_regex_with_capturing_groups => $valid_string_with_placeholders

Capturing groups are referenced using $1, $2, etc.

services:
  searx:
    image: searx/searx:1.0.0-269-7b368146
    labels:
      - wud.tag.include=^\d+\.\d+\.\d+-\d+-.*$$
      - wud.tag.transform=^(\d+\.\d+\.\d+-\d+)-.*$$ => $$1

5. Enable Digest Watching​

In addition to semver tag tracking, you can track whether the remote image digest for a mutable tag (such as latest, 10, or stable) has changed on the registry:

services:
  redis:
    image: redis:alpine
    labels:
      - wud.watch.digest=true

6. Link Container Versions to Changelogs / Release Notes​

You can generate a direct clickable link to release notes using a URL template:

The available template variables are:

  • ${original}: The original unparsed tag
  • ${transformed}: The tag after applying wud.tag.transform
  • ${major}: Major version number
  • ${minor}: Minor version number
  • ${patch}: Patch version number
  • ${prerelease}: Prerelease identifier
services:
  mariadb:
    image: mariadb:10.6.4
    labels:
      - wud.link.template=https://mariadb.com/kb/en/mariadb-$${major}$${minor}$${patch}-changelog

7. Customize Display Name & Icon​

Customize how containers appear in the WUD Web UI and smart home integrations (e.g. Home Assistant):

Supported Icons​

WUD supports the full Iconify catalog (over 150,000+ open-source icons across 150+ collections) using the standard collection:icon-name format:

  • mdi: for Material Design Icons (mdi:database, mdi:docker)
  • simple-icons: (or si:) for Simple Icons (simple-icons:mysql, si:mariadb)
  • selfhst: (or sh:) for Selfh.st Icons (selfhst:authentik, selfhst:jellyfin)
  • logos: for SVG Logos (logos:redis, logos:postgresql)
  • fa6-solid:, fa6-regular:, fa6-brands: (or fa:, fas:, far:, fab:) for Font Awesome (fa6-brands:github, fa:heart)
  • Any other collection from Icon-sets (e.g. lucide:, tabler:, devicon:, etc.)

:::info Legacy Prefixes & Backward Compatibility

  • Legacy prefixes (mdi-, si-, sh-, fa-, fab:, etc.) are automatically normalized.
  • The hl: and hl- (Homarr) prefix is deprecated and automatically mapped to selfhst:.
  • Specifying an icon name without any prefix (e.g. mariadb) defaults to simple-icons:mariadb. :::
services:
  mariadb:
    image: mariadb:10.6.4
    labels:
      - wud.display.name=Production MariaDB
      - wud.display.icon=si:mariadb

8. Assign Specific Triggers & Thresholds​

Route notifications or auto-updates for a specific container to designated triggers:

Threshold Levels​

  • all: Triggers on all updates (semver & digest).
  • major: Triggers on major, minor, or patch updates.
  • minor: Triggers only on minor or patch updates.
  • patch: Triggers only on patch updates.

Example: Send Email for All Updates, Auto-Update on Minor/Patch Only​

services:
  web_app:
    image: web_app:1.2.0
    labels:
      - wud.trigger.include=smtp.gmail,dockercompose.local:minor