Skip to main content

DNS-over-HTTPS and DNS-over-TLS server and forwarder.

Project description



License Releases Downloads

Issues | Pull requests | Contributors

Encrypted-DNS operates as a DNS server that forward DNS queries over UDP, TCP, TLS or HTTPS, thus preventing your device from DNS cache poisoning and censorship. It could also cache DNS records to accelerate further queries, block specific client, and ignore particular domain names.


  • Encrypted DNS upstream servers (DNS-over-HTTPS, DNS-over-TLS)
  • Improve accuracy with EDNS-Client-Subnet
  • Authenticate DNS response with DNSSEC
  • Transparent redirection of specific domains to specific resolvers
  • Send queries through HTTP proxies
  • Cache DNS response with default or customized TTL to reduce latency
  • Force Safe search on search engines (Google, DuckDuckGo, Bing, etc.)
  • Firewall rules: Rate limiting, client blacklist, and disable AAAA or ANY lookups.


  • Install Python 3.6+

  • Install encrypted-dns package via pip

$ python3 -m pip install encrypted-dns
  • Generate and edit config file
$ sudo encrypted-dns
$ vim ~/.config/encrypted_dns/config.json
  • Run Encrypted-DNS Server
$ sudo encrypted-dns
  • Test DNS Lookup
Linux or MacOS:
$ dig @

$ nslookup
  • Change DNS Address to


Encrypted-DNS will generate a JSON file ~/.config/encrypted_dns/config.json


Encrypted-DNS will listen on the address and ports to receive DNS lookups.

The format of each inbound is protocol://address:port.

Currently, Encrypted-DNS only supports inbounds with udp and tcp protocols.

If protocol is not provided, Encrypted-DNS will listen to this inbound address through the udp protocol.

If port is not provided, Encrypted-DNS will use the default port of each protocol. (53 for udp and tcp)

'inbounds': [


Encrypted-DNS will forward the DNS quires to the upstream DNS servers.

The Outbounds is a JSON array of DNS groups.

Here is an example of a DNS group:

'outbounds': [
        'tag': 'unencrypted',
        'dns': ['', 'tcp://'],
        'concurrent': False,
        'domains': ['',', '']
        'tag': 'encrypted',
        'dns': ['', 'tls://'],
        'proxies': {
            'http': '',
            'https': ''
        'concurrent': False,
        'domains': ['all']

tag is the name of the DNS group

dns is an array of DNS upstreams

  • The format of each upstream is protocol://address:port
  • Encrypted-DNS supports these protocols: udp, tcp, tls, https
  • If protocol is not provided, Encrypted-DNS will connect to the upstream through udp protocol.
  • If port is not provided, Encrypted-DNS will use the default port of each protocol. (53 for udp and tcp, 853 for tls, 443 for https)


  • If concurrent is True, Encrypted-DNS will forward queries to all servers in this group concurrently and send the first response to the client
  • If concurrent is False, Encrypted-DNS will forward queries to a random server in this group.

Encrypted-DNS will only forward queries to this group only if the domain is included in the domains. For example:

  • exact domain
  • subdomains of, such as,
  • domains include, such as,, whatisnetflix.command
  • all: all domains

Bootstrap DNS Group

Encrypted-DNS will send DNS queries to the server in the bootstrap DNS group to retrieve the IP addresses of DNS-over-HTTPS or DNS-over-TLS server.

If the group is not specified, Encrypted-DNS will use to resolve the IP addresses.

'outbounds': [
        'tag': 'bootstrap',
        'dns': ['', '']

DNS Cache

Cache DNS responses to reduce latency for further queries.

If override_ttl is -1, Encrypted-DNS will use default TTL for each record.

'dns_cache': {
    'enable': True,
    'override_ttl': 3600


  • refuse_ANY will ignore all queries with ANY type since it's often used in DNS reflection attacks.
  • AAAA_disabled will ignore all quires with AAAA type.
  • rate_limit will limit the amount of quires Encrypted-DNS could process every minute.
  • client_blacklist will ignore all quires sent by specific clients.
'firewall': {
    'refuse_ANY': True,
    'AAAA_disabled': False,
    'rate_limit': 30,
    'client_blacklist': [
    `   ''


  • force_safe_search will enable Safe search on search engines: Google, Bing, Yahoo, DuckDuckGo, and Youtube.
  • hosts will specify A record or CNAME record for domain names.

Rules to match domain in hosts:

  • exact domain
  • subdomains of, such as,
  • domains include, such as,, whatisnetflix.command
  • all: all domains
'rules': {
    'force_safe_search': False,
    'hosts': {
        'localhost': '',
        '': '',
        '': ''

EDNS Client Subnet

EDNS Client Subnet is a DNS extension that allows Encrypted-DNS to specify the network subnet for the host on which behalf it is making a DNS query.

This is generally intended to help speed up the delivery of data from CDN, by allowing better use of DNS-based load balancing to select a service address serving the content expected to be hosted at that domain name, when the client computer is in a different network location from the recursive resolver.

To disable this feature, set ecs_ip_address to null.

'ecs_ip_address': ''

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

encrypted-dns-1.2.0.tar.gz (13.7 kB view hashes)

Uploaded source

Built Distribution

encrypted_dns-1.2.0-py3-none-any.whl (19.7 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page