Overview

DNX is a small Python CLI and library for viewing and changing per-interface DNS servers on Linux, macOS, and Windows. It picks a sensible backend automatically (e.g. systemd-resolved, NetworkManager, or /etc/resolv.conf on Linux; PowerShell DNS cmdlets on Windows; networksetup on macOS), validates IP addresses, and can ping resolvers to show latency before or after you switch. Operations that change system DNS typically require administrator privileges.

PyPI Counter
Github Stars

Branch	main	dev
CI

Code Quality

Installation

Source Code

• Download Version 0.1 or Latest Source
• pip install .

PyPI

• Check Python Packaging User Guide
• pip install dnx==0.1

Usage

In Python

Backend and current DNS

>>> from dnx.dns import get_backend, get_platform, Platform
>>> get_platform()
<Platform.LINUX: 'linux'>
>>> backend = get_backend()
>>> backend.get_dns()
['192.168.1.1']

Set DNS (requires admin / elevated process)

>>> from dnx.dns import get_backend
>>> backend = get_backend()
>>> backend.set_dns(["8.8.8.8", "8.8.4.4"])
>>> backend.get_dns()
['8.8.8.8', '8.8.4.4']

Ping helpers

>>> from dnx.ping import ping_server, verify_servers
>>> ping_server("1.1.1.1", count=2)
PingResult(ip='1.1.1.1', reachable=True, ...)
>>> verify_servers(["8.8.8.8", "1.1.1.1"])
(True, [PingResult(...), PingResult(...)])

Exceptions

>>> from dnx.exceptions import DNXError, InvalidIPError
>>> from dnx.dns import validate_ips
>>> validate_ips(["999.0.0.1"])
Traceback (most recent call last):
...
InvalidIPError: ...

CLI

ℹ️ You can use dnx or python -m dnx to run this program.

Version

> dnx --version
dnx 0.1

List presets

> dnx list
google: 8.8.8.8, 8.8.4.4
cloudflare: 1.1.1.1, 1.0.0.1
...

List presets with latency

ℹ️ Sends a few ICMP probes per preset IP (may require permission for raw ping on some systems).

> dnx list --latency
Checking latency for all presets...

google:
  8.8.8.8: 12.3ms avg (0% loss)
  ...

Current DNS

> dnx current
Current DNS servers:
  192.168.1.1

Current DNS with latency

> dnx current --latency
Current DNS servers:
  1.1.1.1

Latency:
  1.1.1.1: 8.1ms avg (0% loss)

Set DNS (preset or IPs)

ℹ️ set and reset require an elevated shell (e.g. Administrator on Windows, sudo on Linux/macOS).

> dnx set cloudflare
Using preset 'cloudflare': 1.1.1.1, 1.0.0.1
DNS updated successfully!

Latency comparison:
  Before:
    192.168.1.1: 2.1ms avg (0% loss)
  After:
    1.1.1.1: 9.0ms avg (0% loss)

> dnx set 9.9.9.9 149.112.112.112 --verify

ℹ️ --verify pings first and asks before continuing if a server is unreachable. --no-latency skips the before/after latency block.

Ping only

ℹ️ Preset name or one or more IP addresses. Use -c / --count for probe count.

> dnx ping cloudflare -c 4
Pinging 2 server(s)...

1.1.1.1: 7.5ms avg (0% loss)
1.0.0.1: 8.2ms avg (0% loss)

Reset to system default

> dnx reset
DNS reset to system default

Interface override

ℹ️ When auto-detected interface is wrong (VPN, multiple NICs), pass --iface before the subcommand:

> dnx --iface "Wi-Fi" current

Issues & Bug Reports

Just fill an issue and describe it. We'll check it ASAP! You can also email dnx@openscilab.com.

• Please complete the issue template

You can also join our discord server

Show Your Support

Star This Repo

Give a ⭐️ if this project helped you!

Donate to our project

If you do like our project and we hope that you do, can you please support us? Our project is not and is never going to be working for profit. We need the money just so we can continue doing what we do ;-) .

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

Added

Changed

0.1 - 2026-06-22

Added

• Platform enum
• get_platform function
• exceptions module
• DNSBackend class
• get_backend and get_linux_backend functions
• SystemdResolvedDNS, NetworkManagerDNS, and ResolvConfDNS classes
• MacOSDNS and WindowsDNS classes
• ping module
• cli module
• test.yml workflow
• version_check.py script
• Test workflow