EnvCleaner: Windows Environment Variable Manager

EnvCleaner is a desktop application for Windows. It manages User and System environment variables. The application scans path lists, pinpoints non-existent directories, removes duplicate entries, stages in-editor cleanups, and backs up registry values.

---

Key Features

• Dead Path Detection: Automatically flags non-existent directories and files in PATH and other list variables.
• Duplicate Removal: Detects duplicate entries using case-insensitive and trailing-slash normalization.
• Dynamic Variable Resolution: Resolves expressions like %USERPROFILE% and %SystemRoot% before testing disk existence.
• In-Editor Staged Cleaning: Remove dead paths or duplicates directly in the Path table. Review the remaining entries before saving to the registry.
• Global Quick Clean: Scan all variables across User and System scopes at once. Review proposed removals in an interactive checklist modal before applying.
• Ordered Path Editor: Reorder path segments with dedicated Move Up and Move Down controls.
• Automatic Backups: Generates timestamped JSON and native Windows .reg snapshots before any write operation.
• Point-and-Click Rollback: Restore previous environment configurations directly from the snapshot manager.
• Registry Integration: Edits User (HKCU) and System (HKLM) registry entries directly.
• Live System Broadcast: Dispatches WM_SETTINGCHANGE so running shells pick up changes immediately without rebooting.
• Administrator Elevation: Detects standard permissions and provides a one-click restart for administrator rights.
• Theme Support: Includes both dark and light modes matching Windows 11 Fluent style.

---

Getting Started

Option 1: Standalone Executable (Recommended)

No Python installation is required.

1. Download EnvCleaner.exe or EnvCleaner-v1.0.0-windows-x64.zip from GitHub Releases.
2. Run EnvCleaner.exe.
3. To edit System environment variables (HKLM), right-click EnvCleaner.exe and select Run as administrator, or click Restart as Administrator inside the application header.

---

Option 2: Run from Source

Prerequisites

• Operating System: Windows 10 or Windows 11.
• Python: Python 3.10 or newer (tested on Python 3.14).

Installation

1. Clone the repository:

   git clone https://github.com/FunToHard/EnvCleaner.git
   cd EnvCleaner

2. Install dependencies:

   pip install -r requirements.txt

Running the Application

• Standard User:

  run.bat

  Or using Python:

  python -m envcleaner

• Administrator Elevation:

  run.bat --admin

  Or click Restart as Administrator inside the application header.

Command Line Options

• --light: Start the application in light mode.
• -v, --version: Display the application version.

---

How It Works

1. Registry Inspection

EnvCleaner loads environment variables from two Windows Registry locations:

• User Scope: HKEY_CURRENT_USER\Environment
• System Scope: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment

The scanner parses delimited strings into distinct path entries, resolves dynamic %...% expressions, and checks each path on disk using os.path.exists().

2. Path Status Badges

• Valid (Green): The directory or file exists on disk.
• Missing (Red): The target path does not exist on disk.
• Duplicate (Amber): The path already appeared earlier in the list.
• Syntax Error (Violet): The path contains illegal characters (< > " | ? *) or extra colons.
• Empty (Gray): A redundant semicolon created an empty entry segment.

3. Cleaning Modes

• In-Editor Staged Cleanup: Inside the Path Inspector, clicking Remove Missing or Remove Duplicates removes invalid rows directly from the active table in place. The live character length updates immediately. Click Save Changes to Registry to commit, or Discard Changes to revert.
• Global Quick Clean: Clicking Quick Clean Issues... in the top status bar collects all issues across all variables. It opens an interactive checklist modal allowing you to select or deselect specific removals before applying.

4. Backup and Safety Engine

Before applying any change or deletion to the registry, EnvCleaner automatically saves:

1. A full JSON snapshot to %USERPROFILE%\.envcleaner\backups\.
2. A standard .reg file importable directly in Windows Registry Editor.

Use the Backups & Snapshots dialog to view history, export .reg files, or restore previous configurations at any time.

---

Running Automated Tests

Run the complete test suite:

python -m unittest discover -s tests -p "test_*.py" -v

All 24 automated unit and UI tests run headlessly using Qt offscreen mode (QT_QPA_PLATFORM=offscreen).

---

Building Self-Contained Releases

You can compile EnvCleaner into a standalone Windows executable (EnvCleaner.exe):

Local Compilation

Run the build script:

build.bat

Or with Python:

python build.py

The build script runs all 24 automated tests, invokes PyInstaller, and produces:

• dist/EnvCleaner.exe: Standalone single-file Windows executable.
• dist/EnvCleaner-v1.0.0-windows-x64.zip: Release archive containing the executable, README.md, and LICENSE.

Automated GitHub Releases

The repository includes a GitHub Actions workflow in .github/workflows/release.yml. Pushing a version tag triggers automated testing, compilation on a Windows runner, and publication of release assets to GitHub Releases:

git tag v1.0.0
git push origin v1.0.0

---

License

This project is licensed under the MIT License.