ChDNSChanger

Elite Cross‑Platform DNS Manager with CLI & GUI

---

ChDNSChanger is a professional, cross‑platform DNS management tool that lets you instantly switch between popular DNS providers, run latency tests before applying changes, save custom configurations, and revert to DHCP – all from a sleek dark GUI or a powerful command‑line interface.

---

📋 Table of Contents

• 👨‍💻 Project Programmer
• 🧠 Made For
• 🖼️ Screenshots / Preview
• ⚓ Requirements
  • 📦 Installing Dependencies
• ⚙️ Installation Guide
  • Linux
  • Windows
  • macOS
• 💻 Supported Platforms
• ✨ Features
  • 🎯 Core Capabilities
  • 🎨 User Experience
• 💻 Usage
  • Command Line Interface (CLI)
    • Interactive Mode
    • CLI Arguments & Examples
  • Graphical User Interface (GUI)
• ⚙️ Configuration
  • Provider JSON File
  • Custom Providers
• 🔍 Advanced Features
  • Latency Test Before Applying
  • Automatic Virtual Adapter Filtering
  • Cross‑Platform Admin Detection
• 📁 Project Structure
• ❤️ Support the Project
• ⚠️ Disclaimer
• 🚨 Reporting Issues
• ❓ Frequently Asked Questions (FAQ)
• 📄 License

---

👨‍💻 Project Programmer

Ch4120N — Ch4120N@Proton.me

---

🧠 Made For

Network administrators, system engineers, privacy‑conscious users, and tech enthusiasts who need to quickly switch DNS providers, test latency, and manage DNS settings across Windows, Linux, and macOS without touching system configuration files.

---

🖼️ Screenshots / Preview

CLI Interactive Menu	GUI Main Window

---

⚓ Requirements

• Python 3.7+
• pip (Python package manager)
• PyQt5 (for the GUI version)
• colorama (optional, for Windows console colors)

📦 Installing Dependencies

python -m pip install -r requirements.txt

The requirements.txt file should contain:

PyQt5>=5.15
colorama>=0.4

Note: colorama is only needed on Windows for the CLI color output; the tool works without it but will lack colors.

---

⚙️ Installation Guide

Linux

# Install system dependencies (if needed)
sudo apt install python3 python3-pip git -y

# Clone the repository
git clone https://github.com/Ch4120N/ChDNSChanger.git
chmod 755 -R ChDNSChanger/
cd ChDNSChanger/

# Install Python packages
python3 -m pip install -r requirements.txt

# Change directory into src/
cd src/

# Run the CLI (requires sudo for DNS changes)
sudo python3 chDNSChanger.py

# Run the GUI (also needs sudo for actual changes)
sudo python3 chDNSChanger.GUI.py

Windows

Option 1 – Git clone:

git clone https://github.com/Ch4120N/ChDNSChanger.git
cd ChDNSChanger\
python -m pip install -r requirements.txt
cd src\
python chDNSChanger.py          # run CLI
python chDNSChanger.GUI.py      # run GUI

Option 2 – Download ZIP:
Download the latest release, extract it, and run the same commands.

Important: On Windows you must run the scripts as Administrator to modify DNS settings.

macOS

brew install python3 git
git clone https://github.com/Ch4120N/ChDNSChanger.git
cd ChDNSChanger/
python3 -m pip install -r requirements.txt
cd src/
sudo python3 chDNSChanger.py     # CLI
sudo python3 chDNSChanger.GUI.py # GUI

---

💻 Supported Platforms

• Linux (all distributions with resolvectl or /etc/resolv.conf)
• Windows (7, 8, 10, 11)
• macOS (all versions with networksetup)

---

✨ Features

🎯 Core Capabilities

• ⚡ Instant DNS Switching – Choose from a list of popular providers (Google, Cloudflare, OpenDNS, etc.) defined in a JSON file.
• 📡 Pre‑Change Latency Test – Optionally ping new DNS servers before applying; colour‑coded results (green/yellow/red) help you decide.
• 🔄 One‑Click DHCP Revert – Quickly go back to automatic DNS assignment.
• ⚙️ Custom DNS Entry – Enter any custom primary and secondary DNS and optionally save it to the provider list.
• 🌐 True Cross‑Platform – Identical workflow on Windows (netsh), Linux (resolvectl + fallback to /etc/resolv.conf), and macOS (networksetup).
• 🔒 Admin Detection – Automatically detects missing admin/root privileges and disables DNS changes until elevated.
• 🧹 Virtual Adapter Filtering – Ignores virtual adapters (VMware, VirtualBox, VPN, Docker, etc.) to target only physical interfaces.

🎨 User Experience

• 🖥️ Graphical Interface – Sleek, dark‑themed, frameless PyQt5 window with custom title bar, provider list, activity log, and action buttons.
• 💬 Interactive CLI Menu – Colourful terminal menu with adaptive 3‑column layout, showing provider numbers and special options.
• 📝 Activity Log – In the GUI, every action is timestamped and displayed in a scrollable log window.
• 🔍 Update Checker – GUI can fetch the latest release info from GitHub.

---

💻 Usage

Command Line Interface (CLI)

The CLI script (chDNSChanger.py) can be used interactively or with direct arguments.

Interactive Mode

Simply run the script without arguments and follow the menu:

sudo python3 chDNSChanger.py

You'll see the current DNS status, a provider list, and options to:

• Select a provider (1‑N)
• Enter a custom DNS (97)
• Revert to DHCP (98)
• Exit (99)

After choosing a provider, you can optionally run a latency test before applying.

CLI Arguments & Examples

Argument	Short	Description
--status	-s	Show current DNS information
--list	-l	List all available DNS providers
--set NAME	-S	Apply DNS of a specific provider (by name)
--custom ...	-c	Apply custom DNS: NAME PRIMARY [SECONDARY]
--save		Save custom provider to JSON file (use with --custom)
--ping		Perform latency test before applying (with --set or --custom)
--revert	-r	Revert DNS to DHCP
--version	-v	Show version and exit
--help	-h	Show help message

Examples:

# List providers
sudo python3 chDNSChanger.py -l

# Show current status
sudo python3 chDNSChanger.py -s

# Set to Google DNS after a ping test
sudo python3 chDNSChanger.py --set Google --ping

# Apply custom DNS and save it as "MyDNS"
sudo python3 chDNSChanger.py --custom MyDNS 8.8.4.4 8.8.8.8 --save

# Revert to DHCP
sudo python3 chDNSChanger.py -r

Graphical User Interface (GUI)

Launch the GUI with:

sudo python3 chDNSChanger.GUI.py    # Linux / macOS
python chDNSChanger.GUI.py          # Windows (as Administrator)

Main window sections:

1. Current Status – Shows active interface and current DNS servers.
2. Provider List – Click to select a provider; primary/secondary displayed on the right.
3. Actions – Buttons to apply DNS, test latency, revert to DHCP, add custom DNS, refresh status, and clear logs.
4. Activity Log – Real‑time log of all operations with colour‑coded messages.
5. Bottom Bar – Check for updates, open About dialog, link to source code.

All buttons are disabled unless admin/root privileges are detected.

---

⚙️ Configuration

Provider JSON File

The tool reads provider definitions from either servers.json located in the project root or the current working directory. The format is:

{
  "Google": {
    "enable": true,
    "primary": "8.8.8.8",
    "secondry": "8.8.4.4"
  },
  "Cloudflare": {
    "enable": true,
    "primary": "1.1.1.1",
    "secondry": "1.0.0.1"
  }
}

• enable – set to false to disable a provider (it will appear greyed out in the GUI).
• secondry – set to "null" if no secondary DNS is desired.

Custom Providers

You can add providers manually by editing the JSON file, or use the GUI’s “Custom DNS” option that optionally saves new entries to the config file.

---

🔍 Advanced Features

Latency Test Before Applying

Both CLI and GUI let you ping the new DNS servers before applying. The tool sends 4 pings and reports:

• Excellent (< 90 ms) – green
• Good (90‑160 ms) – yellow
• Bad (> 160 ms or unreachable) – red

You can then choose to proceed or cancel.

Automatic Virtual Adapter Filtering

Many systems have virtual adapters (VPN, VMware, Docker, etc.). ChDNSChanger automatically filters them out using a comprehensive keyword list, ensuring DNS changes are applied only to the real physical connection.

Cross‑Platform Admin Detection

The tool checks for root on Unix‑like systems and Administrator rights on Windows. If missing, both CLI and GUI will warn you and disable the apply/revert buttons.

---

📁 Project Structure

ChDNSChanger/
├─ images/                       # Screenshots and logos
├─ src/
│  ├─ config/
│  │  ├─ config.py
│  │  └─ servers.json
│  ├─ core/
│  │  ├─ dns_managers.py
│  │  └─ provider.py
│  ├─ resources/
│  │  ├─ img/
│  │  │  ├─ broom.svg
│  │  │  ├─ git.svg
│  │  │  ├─ info.svg
│  │  │  ├─ logo.svg
│  │  │  ├─ pencil.svg
│  │  │  ├─ play.svg
│  │  │  ├─ radar.svg
│  │  │  ├─ refresh.svg
│  │  │  ├─ sync.svg
│  │  │  ├─ timer.svg
│  │  │  └─ undo.svg
│  │  │
│  │  └─ fonts/ 
│  ├─ ui/
│  │  ├─ cli/
│  │  │  ├─ banner.py
│  │  │  ├─ colors.py
│  │  │  ├─ decorators.py
│  │  │  └─ menu.py
│  │  └─ gui/
│  │     ├─ about.py
│  │     ├─ messagebox.py
│  │     ├─ splash_screen.py
│  │     └─ titlebar.py
│  ├─ utils/
│  │  ├─ gui/
│  │  │  ├─ dns_worker.py
│  │  │  ├─ ping_worker.py
│  │  │  └─ status_worker.py
│  │  ├─ executor.py
│  │  ├─ ping.py
│  │  └─ utils.py
│  ├─ chDNSChanger.py
│  └─ chDNSChanger.GUI.py
├─ .gitignore
├─ README.md
└─ requirements.txt

The source code you receive is a consolidated version; the modular structure above is the recommended packaging.

---

❤️ Support the Project

If you find this tool useful, consider donating:

Cryptocurrency	Address
BTC	bc1ql4syps7qpa3djqrxwht3g66tldyh4j7qsyjkq0
ETH	0xfddbd535a4ad28792cbebceee3d6982d774e6d13
USDT	3Cq6HRQsiwZFmPEQfG9eJkZE2QGChvf2VN

💖 Your support helps keep the project alive and improving!

---

⚠️ Disclaimer

This tool modifies network settings and requires administrator/root privileges.

• ✅ Use it only on systems you own or manage.
• ⚠️ Always verify DNS server IPs; incorrect settings may disrupt network connectivity.
• 🛑 The author is not responsible for any network issues caused by misuse.

---

🚨 Reporting Issues

Encountered a bug or have a suggestion?
📩 Ch4120N@Proton.me

---

❓ Frequently Asked Questions (FAQ)

What is ChDNSChanger?

ChDNSChanger is a cross‑platform DNS management tool that provides both a command‑line and a graphical interface to quickly switch DNS servers, perform latency tests, and revert to DHCP – all without manually editing network settings.

Do I need admin rights?

Yes. Changing DNS settings is a system‑level operation. The tool will warn you and disable functions if you are not running as administrator (Windows) or root (Linux/macOS).

Can I add my own DNS providers?

Absolutely! You can edit the servers.json file directly, or use the GUI’s “Custom DNS” feature that offers to save new entries to the configuration file.

Does it work on all Linux distributions?

It primarily uses resolvectl (systemd‑resolved) which is present on most modern Linux distributions. If resolvectl fails, it falls back to directly editing /etc/resolv.conf (with a backup of the original file). For very old systems, this fallback ensures compatibility.

How does the latency test work?

The tool sends 4 ICMP echo requests to each DNS server and calculates the average round‑trip time. Results are colour‑coded for quick evaluation. You can choose to skip the test if you’re in a hurry.

Is there a difference between CLI and GUI versions?

Both offer the same core functionality. The CLI is suitable for scripting and headless environments; the GUI provides a more user‑friendly experience with a real‑time log, visual provider selection, and update checking.

Can I revert to DHCP easily?

Yes. Both the CLI and GUI have a dedicated “Revert to DHCP” option. On Linux, it restores the original /etc/resolv.conf if a backup was created; otherwise it uses resolvectl revert.

---

📄 License

This project is licensed under the GNU General Public License (GPL) v3.0.

---

"Instant DNS switching, smart latency tests, and total control – one tool for every platform."

⭐ If you like this project, don't forget to give it a star!

Made with ❤️ by Ch4120N