Cloudflare DDNS

A small, safety-focused dynamic DNS updater for Cloudflare. It supports multiple zones, multiple A and AAAA records, configuration reloads between cycles, dry runs, and an optional guarded pruning mode.

Release status: This project is an initial public alpha. Test with --dry-run before allowing it to change DNS records.

Safety model

• API tokens are read only from CF_API_TOKEN; never place them in YAML.
• The example configuration uses reserved example.com names.
• Record creation is configurable and disabled by default when omitted.
• Record pruning is disabled by default.
• Pruning requires both prune_unlisted_a_records: true and --allow-prune.
• --dry-run performs reads and reports planned writes without changing DNS.

Pruning applies to every A record in each configured zone. When enabled, an A record whose normalized name is absent from the configuration will be deleted. Always inspect a dry run before using --allow-prune.

Requirements

• Python 3.10 or newer
• A Cloudflare API token with Zone:Read and DNS:Edit permissions, scoped only to the zones the updater manages

Installation

python -m venv .venv

Activate the environment:

.venv\Scripts\Activate.ps1

On macOS or Linux, use source .venv/bin/activate. Then install:

python -m pip install --editable .

Configuration

Copy config.example.yaml to a location outside the repository and replace the reserved example names with your own records. Set the token in the process environment:

$env:CF_API_TOKEN = "your-scoped-token"

On macOS or Linux:

export CF_API_TOKEN="your-scoped-token"

Preview a single update cycle:

cloudflare-ddns --config config.yaml --once --dry-run

Apply changes continuously:

cloudflare-ddns --config config.yaml

If pruning is intentionally enabled in the configuration, preview it first and then add the separate authorization flag:

cloudflare-ddns --config config.yaml --once --dry-run --allow-prune
cloudflare-ddns --config config.yaml --allow-prune

Running with systemd

The systemd/cloudflare-ddns.service file is a reference unit. Review its paths, install the project in /opt/cloudflare-ddns, keep the configuration and environment file under /etc/cloudflare-ddns, and restrict the environment file to the service administrator.

Development

python -m pip install --editable ".[dev]"
ruff check .
pytest

License

MIT © 2026 CodeVelo.dev LLC.