Installation guides
How to Install dnscrypt-proxy Version 2 on Any Platform
dnscrypt-proxy is a small DNS client that runs on your own computer or router. It listens for ordinary queries on a local address, then forwards them over an encrypted channel to resolvers you pick. Along the way it caches answers, can block names from lists and can log every lookup, which makes it as useful for diagnosis as for privacy.
What dnscrypt-proxy version 2 does
The current branch is version 2, written in Go and published as one executable per platform. According to its README it speaks DNSCrypt v2 (including the post-quantum variant), DNS-over-HTTPS over TLS 1.3 and QUIC, Anonymized DNSCrypt relays and Oblivious DoH. You can mix protocols freely, and the proxy measures each resolver and balances traffic across the fastest ones.
Release 2.1.20 appeared on 22 October 2026, two days after 2.1.19. Its notes add regex: rules for name lists, an option called doh_check_cert_hashes_on_connect, and fixes to post-quantum DNSCrypt padding over TCP. The full history of builds lives on the release archive, and the protocol background is on the encrypted DNS overview.
The install pattern every platform shares
Whatever the operating system, version 2 is installed the same way, and the per-platform guides only change the paths, the privilege command and the place where DNS servers are set. Learning the pattern once saves a lot of confusion later, because most failed installs come from doing the steps out of order rather than from a broken binary.
- Download the archive for your system from the GitHub releases page.
- Verify it against its
.minisigfile. - Extract it and copy the example TOML file to the real configuration name.
- Start the proxy in the foreground with elevated rights and read its log lines.
- Send a test query with
-resolve example.com. - Point the system DNS at
127.0.0.1. - Stop the foreground copy and register it with
-service install.
The order matters most around steps four to six. Leave the system DNS alone until the proxy has started cleanly and resolved a name; otherwise a typo in the configuration file leaves the machine with no working DNS. The project wiki is blunt: start with stock settings, confirm they work, then change options one at a time.
Picking the right release file
The releases page lists dozens of files because each operating system and CPU gets its own build. Linux users mostly want linux_x86_64, Raspberry Pi owners linux_arm64 or linux_arm, 64-bit Windows the win64 zip, and Macs either macos_arm64 or macos_x86_64. Windows builds are also offered as MSI packages for x64 and x86 machines.
Distribution packages are the other route: Homebrew on macOS, the Debian and Ubuntu repositories, Arch Linux, and a dedicated package on OpenWrt. They handle paths and services for you, but updates arrive at the packager’s pace, so a repository build can sit releases behind GitHub. For a router that is often fine; for testing a new feature it is not.
Verifying the download with Minisign
Every archive is signed with Minisign, a tiny signing tool by the same author. Install it, place the archive and its .minisig file in one folder, and run the command below with the project’s public key. On Windows the archive is a zip, so the file name pattern changes accordingly. Copy the whole key: it ends in jB5.
minisign -Vm dnscrypt-proxy-*.tar.gz -P RWTk1xXqcTODeYttYMCMLo0YJHaFEHn7a3akqHlb/7QvIQXHVPxKbjB5
dig txt dnscrypt-proxy.key.dnscrypt.info.
A valid signature proves the file was produced by the key holder and not altered on the way, which matters for a program that will see every name your machine looks up. The second command fetches the same public key through a DNSSEC-signed TXT record, so you can cross-check the key without trusting the page you copied it from.
The configuration file in five settings
The archive ships an example file with every option commented out and explained in place. Copy it rather than starting from a blank file, because those comments are the most complete reference to the settings there is, and they change with releases. Keep the copy next to the executable while you learn, so relative paths for lists and logs resolve.
cp example-dnscrypt-proxy.toml dnscrypt-proxy.toml
| Key | Default in the example | What it decides |
|---|---|---|
listen_addresses | ['127.0.0.1:53'] | Where the proxy accepts queries |
server_names | commented out | A fixed list of resolvers by name |
require_dnssec, require_nolog, require_nofilter | false, true, true | Filters applied when no names are fixed |
ipv6_servers | false | Whether IPv6 resolvers are used |
[anonymized_dns] | empty | Relay routes that hide your IP from the resolver |
The interplay between server_names and the filters trips up many readers. If you name resolvers explicitly, the filters are ignored and only those servers are used. Leave the list commented and the proxy picks from every resolver in its sources that passes the require_* filters. Browse the resolver directory before you commit to fixed names.
Anonymized routes are the part of the configuration file that is easiest to get wrong by hand, because each server needs relays run by someone else, ideally in another country. The route builder generates the [anonymized_dns] block and matching server_names for you, and it can wrap them into a complete file for your platform.
Running dnscrypt-proxy as a service
Once the foreground test passes, stop it and register the same binary as a system service from the folder that holds both the executable and its configuration. The built-in installer creates a Windows service, a launchd daemon on macOS, or a systemd unit on Linux, and it starts at every boot. Start it the first time with -service start.
./dnscrypt-proxy -service install
The same flag takes stop, restart and uninstall. Upgrading means reading the release notes, running the new binary with -config pointing at the old file plus -check to confirm it parses, then swapping the executable and restarting. If you keep the binary and the TOML file in separate folders, pass -config with an absolute path every time.
Platform guides
- Windows: the command-line service, Simple DNSCrypt and the adapter settings
- macOS: Homebrew or the release zip, plus System Settings and
networksetup - Linux: distribution packages, systemd and port 53 conflicts
- Android: client apps, the Magisk module and Private DNS
- iOS: encrypted DNS profiles and apps on iPhone and iPad
- OpenWrt: the router package, dnsmasq forwarding and LuCI
Which guide you need depends less on the device than on how far the protection should reach. A router install covers every phone, television and laptop on the network. A desktop install follows the laptop to hotels and airports. Phones rarely run the proxy directly; apps embed it, or the system’s own encrypted DNS does the job.
Checking that it works
The quickest test is the built-in resolver check. It prints which upstream server answered, whether the reply was DNSSEC signed and which addresses came back. If the resolver line names your internet provider instead of a server from your list, the system is still bypassing the proxy and the DNS setting needs another look.
./dnscrypt-proxy -resolve example.com
For a second opinion from outside the machine, the DNS leak check lists commands that ask well-known services which resolver address reached them. Run them after every network change: a VPN client, a new Wi-Fi network or a system update can quietly restore the old DNS servers, and the proxy keeps running without anything ever reaching it.
Frequently asked questions
Is DNSCrypt something you install?
No. DNSCrypt is a protocol specification. What you install is a client that speaks it, and the most widely used one is dnscrypt-proxy. Server software such as dnsdist or Unbound implements the other side, and graphical tools like Simple DNSCrypt are front ends that manage the same proxy underneath. The install pattern is the same on every operating system.
Which file do I download from the releases page?
Pick the archive that matches both the operating system and the CPU. Most Linux desktops need the linux_x86_64 tar.gz, 64-bit Windows the win64 zip, Apple Silicon Macs the macos_arm64 zip. Each archive has a matching .minisig signature file next to it, which is what the verification step checks. Raspberry Pi owners usually want linux_arm64 or linux_arm.
Why does the proxy say the address is already in use?
Another program already listens on port 53 of the loopback address. Typical culprits are systemd-resolved on Linux, mDNSResponder on macOS when Internet Sharing or a hypervisor is active, a VPN client, or an earlier instance of the proxy that was never stopped. Stop the other service or move the proxy to a different address.
How do I upgrade to a new release?
Read the release notes for configuration changes, run the new binary with -check against the existing configuration file, then replace the old executable and restart the service. The configuration and the lists stay where they are, so an upgrade is normally a one-file swap. If the binary and the TOML file sit apart, pass -config with an absolute path.
Can the proxy run without administrator rights?
Binding to port 53 needs elevated rights on all desktop systems, so the first start and the service installation run as administrator or root. On Linux and macOS the user_name setting lets the process drop to an unprivileged account after it has opened the port. Leave system DNS untouched until that first run resolves a test name.