hyper2kvm

Installation

Table of Contents

• Quick Start
• Shell Completion (Optional)
• System Dependencies by OS
  • Linux
  • macOS
  • Windows (WSL)
• Running
• Developer Install

Quick start (recommended: editable install)

git clone https://github.com/ssahani/hyper2kvm.git
cd hyper2kvm

python3 -m venv .venv
source .venv/bin/activate

python -m pip install -U pip wheel setuptools
python -m pip install -r requirements.txt
python -m pip install -e .

# sanity check
python -m hyper2kvm --help
# or, if you keep the launcher:
python ./hyper2kvm.py --help

Shell Completion (Optional)

Enable intelligent tab completion for bash, zsh, or fish shells. This provides automatic completion for all command-line arguments and options.

Prerequisites:

# Install argcomplete (required for shell completion)
pip install argcomplete

# Or via system package manager
sudo dnf install python3-argcomplete  # Fedora/RHEL/CentOS
sudo apt install python3-argcomplete  # Debian/Ubuntu
sudo pacman -S python-argcomplete     # Arch Linux
brew install argcomplete              # macOS

Installation:

# Interactive installation (recommended)
./completions/install-completions.sh

# Or install for a specific shell
./completions/install-completions.sh bash
./completions/install-completions.sh zsh
./completions/install-completions.sh fish

# Install for all shells
./completions/install-completions.sh all

Usage:

After installation, you can use tab completion:

hyper2kvm --<TAB>              # Shows all available options
hyper2kvm --vm<TAB>            # Completes to --vmdk, --vm-name, etc.
hyper2kvm --vmdk /path/<TAB>   # Path completion

For detailed installation instructions and troubleshooting, see completions/README.md.

System dependencies by OS

hyper2kvm is Python with a pure Python VMCraft engine for VM manipulation. You need:

• qemu-img (from qemu) - Required for disk conversion
• libvirt - Only if you use --libvirt-test
• openssh-client / scp - For fetch-and-fix and live-fix
• optional: pyvmomi + requests - For vsphere downloads/actions
• optional: watchdog - For daemon watch mode

Note: hyper2kvm uses the native VMCraft engine (pure Python, no C dependencies). No external C dependencies required.

---

Linux

Fedora / RHEL / CentOS Stream

sudo dnf install -y \
  python3 python3-pip python3-virtualenv \
  qemu-img qemu-kvm \
  openssh-clients rsync \
  libvirt-client libvirt-daemon-kvm

Ubuntu / Debian

sudo apt-get update
sudo apt-get install -y \
  python3 python3-pip python3-venv \
  qemu-utils \
  openssh-client rsync \
  libvirt-clients libvirt-daemon-system qemu-system-x86

openSUSE / SLES

sudo zypper install -y \
  python3 python3-pip python3-virtualenv \
  qemu-tools \
  openssh rsync \
  libvirt-client libvirt-daemon-qemu

Arch Linux / Manjaro

sudo pacman -Syu --noconfirm \
  python python-pip python-virtualenv \
  qemu-img qemu-system-x86 \
  openssh rsync \
  libvirt virt-manager

# Enable and start libvirtd service
sudo systemctl enable --now libvirtd

Alpine Linux

# Alpine uses apk
sudo apk add --no-cache \
  python3 py3-pip py3-virtualenv \
  qemu-img qemu-system-x86_64 \
  openssh-client rsync \
  libvirt libvirt-daemon libvirt-client

# Start services
sudo rc-service libvirtd start
sudo rc-update add libvirtd
```bash

---

## macOS

macOS support works with the VMCraft engine. For best performance, use Docker option below for full Linux environment.

### Option 1: Using Homebrew

```bash
# Install Homebrew if not already installed
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install QEMU (qemu-img works natively)
brew install qemu

# Install Python dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .
```bash

**Note:** macOS support works with VMCraft engine. Docker option below provides full Linux environment.

### Option 2: Using Docker (Recommended for macOS)

Run hyper2kvm in a Linux container:

```bash
# Build container
docker build -t hyper2kvm .

# Run with volume mounts
docker run -it --rm \
  --privileged \
  -v $(pwd)/input:/input \
  -v $(pwd)/output:/output \
  hyper2kvm local --vmdk /input/disk.vmdk --to-output /output/disk.qcow2
```bash

### Option 3: Use a Linux VM

The most reliable option for macOS users:
1. Install UTM, Parallels, or VMware Fusion
2. Create an Ubuntu or Fedora VM
3. Follow Linux installation instructions inside the VM

---

## Windows (WSL)

hyper2kvm works in **Windows Subsystem for Linux (WSL2)** with some caveats.

### Prerequisites

1. **Install WSL2** (Windows 10/11):
   ```powershell
   # Run in PowerShell as Administrator
   wsl --install -d Ubuntu

1. Enable nested virtualization (required for KVM):

   # Only works on Windows 11 or Windows 10 build 19044+
   # May require enabling in BIOS/UEFI
   

Installation in WSL2

Once inside your WSL2 Ubuntu environment:

# Update package list
sudo apt-get update

# Install system dependencies
sudo apt-get install -y \
  python3 python3-pip python3-venv \
  qemu-utils qemu-system-x86 \
  openssh-client rsync \
  libvirt-clients libvirt-daemon-system

# Clone and install hyper2kvm
git clone https://github.com/ssahani/hyper2kvm.git
cd hyper2kvm

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .
```bash

### Known WSL2 Limitations

- **KVM acceleration** may not work (depends on Windows version and CPU)
- File I/O between Windows and WSL2 can be slow
- Use `/mnt/c/` to access Windows drives

### Workaround: Use Docker Desktop for Windows

```powershell
# In PowerShell (Windows side)
docker run -it --rm --privileged `
  -v C:\VMs\input:/input `
  -v C:\VMs\output:/output `
  hyper2kvm local --vmdk /input/disk.vmdk --to-output /output/disk.qcow2
```bash

---

## Container/Alternative Installation Methods

### Using Docker

Create a `Dockerfile`:

```dockerfile
FROM ubuntu:22.04

RUN apt-get update && apt-get install -y \
    python3 python3-pip python3-venv \
    qemu-utils qemu-system-x86 \
    openssh-client rsync \
    libvirt-clients libvirt-daemon-system \
    git && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY . /app

RUN python3 -m pip install --no-cache-dir -r requirements.txt && \
    python3 -m pip install -e .

ENTRYPOINT ["python3", "-m", "hyper2kvm"]
```bash

Build and run:

```bash
docker build -t hyper2kvm .
docker run -it --rm --privileged \
  -v /path/to/input:/input \
  -v /path/to/output:/output \
  hyper2kvm local --vmdk /input/disk.vmdk --to-output /output/disk.qcow2
```bash

### Using Podman

Podman works the same as Docker:

```bash
podman build -t hyper2kvm .
podman run -it --rm --privileged \
  -v /path/to/input:/input:Z \
  -v /path/to/output:/output:Z \
  hyper2kvm local --vmdk /input/disk.vmdk --to-output /output/disk.qcow2
```bash

**Note:** The `:Z` suffix is required for SELinux systems (Fedora/RHEL).

### Using a Virtual Environment (Recommended for development)

This isolates hyper2kvm's dependencies from system Python:

```bash
# Create virtual environment
python3 -m venv ~/.venvs/hyper2kvm

# Activate it
source ~/.venvs/hyper2kvm/bin/activate

# Install
pip install -r requirements.txt
pip install -e .

# Use it
python -m hyper2kvm --help

# Deactivate when done
deactivate
```bash

---

## Troubleshooting Installation

### "qemu-img: command not found"

**Problem:** QEMU not installed or not in PATH.

**Solution:**
```bash
# Fedora/RHEL
sudo dnf install qemu-img

# Ubuntu/Debian
sudo apt-get install qemu-utils

# Arch
sudo pacman -S qemu-img

# Verify
which qemu-img
qemu-img --version
```bash

### Python version too old

**Problem:** hyper2kvm requires Python 3.10+.

**Solution:**
```bash
# Check Python version
python3 --version

# Ubuntu: Use deadsnakes PPA for newer Python
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.12 python3.12-venv

# Then use python3.12 explicitly
python3.12 -m venv .venv

Re-enable SELinux

sudo setenforce 1

Permanent fix: Use audit2allow to create policy

(Advanced - consult SELinux documentation)

```bash

Or run in a container with --privileged.

---

Running

After installation:

```bash

module entrypoint (preferred)

python -m hyper2kvm –help

or your top-level script

python ./hyper2kvm.py –help ```bash

Examples:

bash sudo python -m hyper2kvm local --vmdk ./mtv-ubuntu22-4.vmdk --flatten --to-output ubuntu.qcow2 --compress sudo python -m hyper2kvm fetch-and-fix --host esxi.example.com --remote /vmfs/volumes/ds/vm/vm.vmdk --fetch-all --flatten --to-output vm.qcow2 sudo python -m hyper2kvm live-fix --host 192.168.1.50 --sudo --print-fstab bash

---

Developer install

Run tests

```bash

Install dependencies

python -m pip install -r requirements.txt python -m pip install -e .

Install test dependencies

pip install pytest pytest-cov pytest-xdist ruff mypy bandit

Run unit tests

python -m pytest tests/unit/ -v

Run with coverage

python -m pytest tests/unit/ –cov=hyper2kvm –cov-report=term-missing

Run specific test file

python -m pytest tests/unit/test_core/test_utils.py -v

Run linting

ruff check hyper2kvm/

Run type checking

mypy hyper2kvm/ –ignore-missing-imports

Run security scan

bandit -r hyper2kvm/ ```bash

Continuous Integration

Tests run automatically on GitHub Actions for every push and pull request:

• Unit tests on Python 3.10, 3.11, 3.12
• Code quality checks (ruff, mypy)
• Security scanning (Bandit, pip-audit)
• Documentation validation

See .github/workflows/ for CI configuration.

This site is open source. Improve this page.