Metadata-Version: 2.4
Name: py-win-ban-hyperv
Version: 0.2.1
Summary: Used to disable Hyper-V virtualization on Windows systems
License-Expression: MIT
License-File: LICENSE
Author: GGN_2015
Author-email: neko@jlulug.org
Requires-Python: >=3.10
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: py-admin-launch (>=0.1.3)
Description-Content-Type: text/markdown

# py-win-ban-hyperv

Disable or restore Hyper-V virtualization on Windows systems.

This package is useful when software such as some Android emulators, nested
virtualization tools, or low-level debugging utilities needs the Windows
hypervisor to be completely disabled. It can also restore the same Windows
features when you want to use Hyper-V, WSL 2, Windows Sandbox, Virtual Machine
Platform, Device Guard, or Credential Guard again.

> This tool changes boot configuration, optional Windows features, and system
> registry values. Run it only from an administrator account and reboot after
> each operation.

## Installation

```powershell
pip install py-win-ban-hyperv
```

## CLI Usage

Disable Hyper-V and related virtualization security features:

```powershell
# you need to reboot after running this script
python -m py_win_ban_hyperv

# schedule a reboot for you after done (in 30s)
python -m py_win_ban_hyperv --reboot

# skip the confirmation prompt for non-interactive use
python -m py_win_ban_hyperv --yes
```

Restore Hyper-V and related virtualization security features:

```powershell
# you need to reboot after running this script
python -m py_win_ban_hyperv --restore

# schedule a reboot for you after done (in 30s)
python -m py_win_ban_hyperv --restore --reboot

# restore non-interactively and schedule a reboot
python -m py_win_ban_hyperv --restore --reboot --yes
```

## Python API

```python
from py_win_ban_hyperv import ban_hyper_v, restore_hyper_v

ban_hyper_v(reboot=False)      # or reboot=True
restore_hyper_v(reboot=False)  # or reboot=True
```

Both functions request administrator privileges through `py-admin-launch` and
then execute the bundled PowerShell scripts.

## How It Works

The Python entry point is intentionally small. It asks for confirmation unless
`--yes` is passed, parses `--restore` and `--reboot`, then launches one
PowerShell script with elevated permissions:

- `ban_hyperv.ps1` disables the Windows hypervisor boot entry, VBS, HVCI,
  Credential Guard, Hyper-V, Virtual Machine Platform, Windows Hypervisor
  Platform, and Windows Sandbox.
- `restore_hyperv.ps1` enables the matching boot, registry, and optional Windows
  feature settings again.
- `dgreadiness_v3.6/DG_Readiness_Tool_v3.6.ps1` is Microsoft's Device Guard and
  Credential Guard readiness tool. The disable flow runs it with `-Disable`; the
  restore flow runs it with `-Enable`.

The disable flow mainly performs these operations:

- `bcdedit /set "{current}" hypervisorlaunchtype off`
- sets Device Guard, HVCI, and LSA registry values to disabled states
- disables Windows optional features with `dism /online /disable-feature`
- runs the DG/CG readiness tool with `-Disable`

The restore flow performs the corresponding reverse operations:

- `bcdedit /set "{current}" hypervisorlaunchtype auto`
- sets Device Guard, HVCI, and LSA registry values to enabled states
- enables Windows optional features with `dism /online /enable-feature /all`
- runs the DG/CG readiness tool with `-Enable`

## Project Components

- `py_win_ban_hyperv/__main__.py` provides the CLI.
- `py_win_ban_hyperv/core.py` exposes the Python API and elevated launcher.
- `py_win_ban_hyperv/ban_hyperv.ps1` contains the disable workflow.
- `py_win_ban_hyperv/restore_hyperv.ps1` contains the restore workflow.
- `py_win_ban_hyperv/dgreadiness_v3.6/` contains the bundled DG/CG readiness
  tool and its policy files.

## Notes

- A reboot is required before Windows fully applies either operation.
- `--reboot` schedules a restart 30 seconds after the PowerShell script
  completes.
- Restoring Hyper-V may re-enable security features that affect other
  virtualization software. Disabling Hyper-V may affect WSL 2, Windows Sandbox,
  Docker Desktop with WSL 2, and other Hyper-V based tools.

