DDNS

Keep DNS records synchronized with the current IPv4 or IPv6 address. A cross-platform dynamic DNS client with no third-party runtime dependencies.

IPv4 + IPv6
Private, public, and custom address sources

15+ DNS providers
Regional, global, and custom integrations

4 ways to run
Docker, binary, pip, or source

Standard library only
No third-party runtime packages

Choose an installation methodCompare Docker, binary, pip, and source

Open Config StudioBuild and validate config.json in the browser

View build, version, and release status

Complete the first update in three steps

1 Install
Choose the runtime that fits the current device.

2 Configure
Select a provider, credentials, and domains.

3 Run
Verify the result, then keep Web mode or a system task running.

After installation, verify the complete execution path with the Debug provider, which never changes real DNS records:

ddns --dns=debug --ipv4=home.example.com --debug

Once the output looks correct, select a real provider in Config Studio and export the configuration.

Choose an installation method

• Docker (recommended): Best for NAS devices, servers, and container platforms. Multi-architecture images run an update task every five minutes by default.
• Standalone binary: Best when Python should not be installed. A single file runs on Windows, Linux, or macOS.
• pip: Best for an existing Python environment. Install with pip install ddns.
• Source: Best when the code needs to be reviewed or customized. Extract it and run python -m ddns.

Linux and macOS users can also install the matching binary with one command:

curl -fsSL https://ddns.newfuture.cc/install.sh | sh

Why it works for long-running deployments

DNS update capabilities

• Manage multiple domains, providers, and configuration files together.
• Resolve IPv4 or IPv6 from interfaces, default routes, public APIs, URLs, regular expressions, or custom commands.
• Find DNS records automatically and create missing records with most providers (except HE.net and No-IP); configure TTL and routing lines where supported.
• Reduce unchanged DNS API requests with a local cache.

Deployment and operations

• Uses only the Python standard library and supports Python 2.7 and Python 3.x.
• Supports HTTP proxies, multi-proxy fallback, SSL verification policies, and custom certificate authorities.
• Includes in-process scheduling in the Web console; headless deployments can still use systemd/cron, launchd, or Windows Task Scheduler.
• Supports configurable log levels, files, formats, and timestamps.

Configuration and credentials

Config Studio processes input in the browser and does not call DNS provider APIs. Validate the structure with the Debug provider before switching to a real provider.

Most runtime configuration fields can be supplied through these methods, in priority order:

1. Command-line arguments: ddns --key=value
2. JSON configuration: Best for multiple domains, providers, or remote configurations
3. Environment variables: Best for Docker and automated deployment

A small set of controls is command-line only; see the CLI reference.

Credential names vary by provider, including API Token, Access Key, and Secret. Follow the matching provider guide for least-privilege access, and remove real credentials from logs, issues, and examples.

DNS providers

• Regional and cloud platforms: AliDNS, Alibaba Cloud ESA, DNSPod China, Tencent Cloud DNS, Tencent Cloud EdgeOne, EdgeOne DNS, Huawei Cloud DNS, DNS.COM / 51DNS, West.cn
• Global providers: Cloudflare, ClouDNS, DNSPod Global, HE.net, NameSilo, No-IP
• Integration and validation: Callback API, Debug

Cloud providers marked in their guides use HMAC-SHA256 request signing. See the complete provider documentation for capabilities, credential formats, and limitations.

Running and automation

Run with a configuration file:

ddns -c config.json

Keep the local console running and synchronize every five minutes in the same process:

ddns -c config.json --interval 5 --open

Providing --interval automatically selects Web mode, so the web word is optional; top-level JSON "interval": 5 does the same. Web also exposes MCP 2026-07-28 Streamable HTTP at /mcp. When the default loopback listener has no token, the Web APIs and /mcp are unauthenticated; non-loopback and wildcard listeners require a shared HTTP token and should be protected by an HTTPS reverse proxy. Saving an interval writes it back to the configuration; pausing and resuming affect only the current process.

Let a local MCP client such as GitHub Copilot inspect cached status or trigger one complete synchronization after user approval:

ddns mcp -c /etc/ddns/config.json

This stdio server uses only the Python standard library, opens no network listener, and does not expose configuration credentials to the model. It supports MCP 2026-07-28 and the 2025-11-25 lifecycle used by GitHub Copilot CLI. See the MCP server documentation for client setup, tools, and limitations.

MCP clients that cannot launch a local process can use the standalone HTTP endpoint:

ddns mcp -c /etc/ddns/config.json --transport http

For a headless deployment, install a system task that runs every five minutes:

ddns task --install 5 -c /etc/ddns/config.json

Inspect it with ddns task --status, then manage it with --enable, --disable, or --uninstall. Do not run it alongside Web mode's internal scheduler. See the CLI documentation for platform-specific behavior.

If a router or modem only supports a legacy DDNS protocol, use edge-ddns-proxy to bridge it to a modern DNS provider API.

Getting help

1. Reproduce the problem with --debug, then rule out network, permission, and operating-system issues.
2. Search Issues for the same error.
3. If it remains unresolved, open an issue with the version, installation method, system environment, and logs or configuration after removing credentials.

For development and extensions, see the provider development guide and configuration system design.

Project

DDNS is released under the MIT License. Source, releases, and change history are available in the GitHub repository.