Skip to content
Get packs

Guide · Open source

How to use ddns-go: install, configure and run it as a service

Updated · written with AI from the project's own documentation and checked against our catalogue data

ddns-go is an open-source tool that detects your current public IPv4 or IPv6 address and updates the matching DNS record with your domain provider. It is useful when your home or office connection has a changing IP and you still want a domain name to reach your machine. This guide shows how to install it, finish setup in the web page, run it as a background service, and run it with Docker.

DDNS-GOjeessy2/ddns-go · ★ 17.5k · MIT

Quick start

  1. 1Download and extract ddns-go. Get the release from the project's Releases page and extract it to a folder you can find again.
  2. 2Install the service. Run the install command for your system so ddns-go runs in the background.
  3. 3Open the setup page. Browse to http://localhost:9876 on the same computer.
  4. 4Choose your DNS provider. Enter the credentials for a supported provider and list the domains to keep updated.
  5. 5Check the logs. Use the log view in the web page, which shows the last 50 entries, to confirm updates are working.

What ddns-go does and who it suits

ddns-go watches your public IP address and, when it changes, updates the DNS record for your domain so the name keeps pointing at your network. It is configured through a web page on your own computer rather than a hosted service.

It fits people who self-host services at home, own a domain with a supported provider such as Aliyun, Tencent Cloud, Cloudflare or DNSPod, and want to run it on Mac, Windows or Linux.

  • Good fit: a home network with a changing IP and a domain you control
  • Not a fit: a DNS provider that is not on the supported list, unless you can use the Callback option with custom request templates
  • Not a fit: a connection without a public IP address, such as behind carrier-grade NAT, since updates cannot reach it

Install ddns-go on Mac, Windows or Linux

Download ddns-go from the project's Releases page and extract it. Then install it as a service so it runs in the background. On Mac or Linux, open a terminal in the folder you extracted and run the install command. On Windows, open cmd as administrator and use the Windows form.

To remove the service later, use the matching uninstall command.

  • Mac/Linux install: run the install command shown below with sudo
  • Windows: open cmd as administrator and run .\ddns-go.exe -s install
  • Uninstall on Mac/Linux: sudo ./ddns-go -s uninstall
  • Uninstall on Windows: .\ddns-go.exe -s uninstall
sudo ./ddns-go -s install

Finish the setup in your browser

After the service is installed, open a browser and go to http://localhost:9876 to complete the initial configuration. This is where you choose your DNS provider, enter its credentials, and list the domains to update.

The web page has a option that keeps the admin page from being reached from the public internet, and it is checked by default. If you enable public access, the project's notes recommend putting a reverse proxy such as Nginx in front of it to use HTTPS. The page also shows the last 50 log entries, which helps when an update fails.

Tune the update behaviour with command-line flags

The install step accepts flags that change how ddns-go runs. The most useful are the listen address, the sync interval in seconds, and the config file path. The README gives two examples: one that syncs every 10 minutes with a custom config file, and one that checks the local IP every 10 seconds but compares with the provider every 30 minutes.

Be careful with short intervals when you fetch the IP from a web API, because that service may rate-limit you.

  • -l listen address
  • -f sync interval in seconds (default is 5 minutes)
  • -cacheTimes check against the provider every N runs
  • -c custom config file path
  • -noweb run without the web service
  • -skipVerify skip certificate verification
  • -dns custom DNS server
  • -resetPassword reset the web password
./ddns-go -s install -f 600 -c /Users/name/.ddns_go_config.yaml

Run ddns-go in Docker with host networking

The Docker method mounts a host folder so the hidden configuration file persists, and uses host networking mode. Replace /opt/ddns-go with any folder on your host. After the container starts, open http://Docker-host-IP:9876 to finish setup.

The README notes that Windows and Mac desktop Docker does not support --net=host, so use the desktop install on those systems. If you cannot use host mode, you can publish port 9876 instead.

  • Image also available as ghcr.io/jeessy2/ddns-go
  • Reset the password in a container with docker exec, then restart it
docker run -d --name ddns-go --restart=always --net=host -v /opt/ddns-go:/root jeessy/ddns-go

Use webhooks and Callback for notifications and custom providers

ddns-go can call a URL when an update succeeds or fails. The URL can include variables such as the new IPv4 address, the update result and the domains. The README includes examples for several chat apps and a Telegram bot project. If the request body is empty, the call is a GET; otherwise it is a POST.

The Callback option supports more DNS providers by letting you define your own request. It runs once for each configured domain line and provides the IP, domain, record type and TTL as variables.

  • Webhook variables include ipv4Addr, ipv4Result, ipv4Domains and timestamp
  • Callback variables include ip, domain, recordType and ttl

What people use it for

  • Keeping a home media or file server reachable under a fixed domain when the ISP changes your IP
  • Updating IPv6 and IPv4 records at the same time on a home network
  • Sending a chat or push notification when your public IP changes
  • Running on a small Linux box or a Docker host that stays on at home

Frequently asked questions

Is ddns-go free?

ddns-go is released under the MIT licence, which the project lists in its metadata. Your DNS provider may charge for your domain or DNS service separately.

What do I need before installing ddns-go?

The source does not list formal prerequisites. You need a domain with a supported DNS provider and a public IP address, and the README says the web page is reached at localhost:9876 after installation.

Which DNS providers does ddns-go support?

The README lists providers including Aliyun, Tencent Cloud, DNSPod, Cloudflare, Huawei Cloud, Baidu Cloud, Porkbun, GoDaddy, Namecheap and NameSilo, among others. If your provider is missing, the Callback option can add it with custom request templates.

How do I install ddns-go as a service?

Download and extract it, then run sudo ./ddns-go -s install on Mac or Linux, or .\ddns-go.exe -s install in an administrator cmd on Windows. Open http://localhost:9876 to configure it.

Why can't I reach ddns-go from outside my network?

The README says the web page has an option to block public access that is checked by default. If you need remote access, enable it and place a reverse proxy with HTTPS in front, as the project's FAQ recommends.

How does ddns-go compare with other DDNS tools?

The source names ddns-telegram-bot, cloudflare-ddns and inadyn as comparable projects, but it does not benchmark them. Choose ddns-go if you want a web-based setup with many providers, and check the other tools for a narrower, single-provider focus.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

ddns-go suits people who run services at home, own a domain with a supported provider, and want a web-based setup that runs in the background on Mac, Windows, Linux or Docker. Skip it if your provider is unsupported and you do not want to write custom Callback templates, or if your connection has no public IP address.

Install options & downloads