Enterprise-Grade VM Migration from Hyper-V, VMware, and Other Hypervisors to KVM/Libvirt
Welcome to the comprehensive documentation for Hyper2KVM, a production-ready VM migration toolkit designed for seamless hypervisor transitions.
| Feature | Status | Documentation |
|---|---|---|
| VMCraft (480+ APIs) | ✅ Production | Complete Guide |
| Local VMDK Migration | ✅ Production | Quick Start |
| Remote ESXi Fetch | ✅ Production | Migration Playbooks |
| OVA/OVF Extraction | ✅ Production | CLI Reference |
| VHD/AMI Import | ✅ Production | CLI Reference |
| Live Fix (SSH) | ✅ Production | Migration Playbooks |
| Batch Processing | ✅ Production | Batch Guide |
| Windows Support | ✅ Production | Windows Guide |
| vSphere Operations | ✅ Production | vSphere Export |
| Kubernetes Operator | ✅ Production | Operator Guide |
| OpenShift Support | ✅ Production | OpenShift Guide |
| Worker Protocol | ✅ Production | Worker Protocol |
| REST API | ✅ Production | REST API |
Goal: Migrate a VMware VMDK to KVM qcow2
# migration.yaml
command: local
vmdk: /vms/windows-server.vmdk
output_dir: /vms/converted
to_output: windows-server.qcow2
out_format: qcow2
fstab_mode: stabilize-all
regen_initramfs: true
compress: true
libvirt_test: true
# Install and run
pip install "hyper2kvm[full]"
hyper2kvm --config migration.yaml
# Import to libvirt
virsh define /vms/converted/windows-server.xml
virsh start windows-server
| Documentation: Beginner Tutorial | Windows Guide |
Goal: Fetch and migrate VM directly from ESXi host
# fetch.yaml
command: fetch-and-fix
host: 192.168.1.100
user: root
identity: ~/.ssh/id_rsa
remote: /vmfs/volumes/datastore1/vm/vm.vmdk
output_dir: /vms/migrated
to_output: vm.qcow2
fstab_mode: stabilize-all
regen_initramfs: true
hyper2kvm --config fetch.yaml
Documentation: Migration Playbooks
Goal: Migrate multiple VMs in parallel
# batch.yaml
command: local
batch_manifest: migrations.json
batch_parallel: 3
batch_continue_on_error: true
output_dir: /vms/batch
// migrations.json
{
"migrations": [
{"vmdk": "/vms/vm1.vmdk", "to_output": "vm1.qcow2"},
{"vmdk": "/vms/vm2.vmdk", "to_output": "vm2.qcow2"},
{"vmdk": "/vms/vm3.vmdk", "to_output": "vm3.qcow2"}
]
}
hyper2kvm --config batch.yaml
Documentation: Batch Migration Guide
Goal: Deploy as a Kubernetes operator
# Install via Helm
helm install hyper2kvm-operator ./helm/hyper2kvm-operator \
--namespace hyper2kvm-system \
--create-namespace
# Create migration job
kubectl apply -f migration-job.yaml
| Documentation: OpenShift Quickstart | Kubernetes Integration |
| Command | Description |
|---|---|
hyper2kvm --config <yaml> |
Execute migration from YAML config (recommended) |
hyper2kvm --cmd local |
Local VMDK/disk migration (alias: migrate) |
hyper2kvm --cmd fetch-and-fix |
Remote ESXi fetch via SSH |
hyper2kvm --cmd ova |
OVA file extraction |
hyper2kvm --cmd ovf |
OVF file extraction |
hyper2kvm --cmd vhd |
VHD file import |
hyper2kvm --cmd ami |
AMI/cloud tarball extraction |
hyper2kvm --cmd raw |
Raw disk image/tarball import |
hyper2kvm --cmd live-fix |
SSH-based live fixing |
hyper2kvm --cmd libvirt-xml |
Parse libvirt XML to manifest |
h2kvmctl status |
Check worker job status |
h2kvmctl submit <config> |
Submit migration job to worker |
hyper2kvm --help |
Show full command reference |
Standard Migration:
1. Create YAML config file
2. Run: hyper2kvm --config migration.yaml
3. Automatic fstab/bootloader fixing
4. Optional: libvirt/QEMU testing
5. Import to libvirt with virsh
Remote Fetch:
1. Configure SSH access to ESXi
2. Create fetch-and-fix YAML config
3. Final switchover (<5s downtime)
4. Validate target
5. Cutover production traffic
Kubernetes Deployment:
1. Install Helm chart or OLM bundle
2. Create MigrationJob CRD
3. Monitor with kubectl/OpenShift console
4. Retrieve converted images
5. Deploy to KubeVirt or export
Beginner (0-2 hours):
Intermediate (2-8 hours):
Advanced (8+ hours):
Enterprise (Full deployment):
| Hyper2KVM Version | Python | Supported Hypervisors | Kubernetes | Status |
|---|---|---|---|---|
| 2.1.0+ | 3.10+ | VMware, Hyper-V, KVM, AWS, Azure, GCP | 1.24-1.33 | ✅ Current |
| 2.0.0 | 3.10+ | VMware, Hyper-V, KVM, AWS, Azure | 1.24-1.30 | ✅ Stable |
| 1.x | 3.10+ | VMware, Hyper-V, KVM | N/A | ✅ Supported |
| 0.9.x | 3.9+ | VMware, Hyper-V, KVM | N/A | 🔄 Legacy |
docs/
├── index.md (this file) # Main documentation hub
├── QUICK_REFERENCE.md # One-page command reference ⭐
├── GLOSSARY.md # Complete terminology guide ⭐
├── FAQ.md # Frequently asked questions ⭐
├── getting-started/ # Installation and first steps (README ⭐)
├── tutorials/ # Step-by-step learning (README ⭐)
├── recipes/ # Quick recipes (README ⭐)
├── guides/ # Task-oriented guides (README ⭐)
│ ├── cli/ # Command-line reference
│ ├── migration/ # Migration workflows
│ ├── tui/ # Terminal UI
│ └── configuration/ # Configuration guides
├── features/ # Feature documentation (README ⭐)
│ └── vmcraft/ # VMCraft engine
├── os-support/ # OS-specific guides (README ⭐)
│ └── windows/ # Windows migration
├── deployment/ # Deployment guides (README ⭐)
│ ├── openshift/ # OpenShift specific
│ └── releases/ # Release notes
├── worker/ # Worker protocol (README ⭐)
├── test-results/ # Test reports (README ⭐)
├── reference/ # API and technical reference (README ⭐)
│ └── api/ # API documentation
├── development/ # Development guides
├── project/ # Project information
├── presentation/ # Presentation materials
├── api/ # Legacy API docs
└── marketing/ # Marketing content
⭐ = New or enhanced in v2.1.0
We welcome contributions! See:
Hyper2KVM is licensed under LGPL-3.0-or-later. See LICENSE file for details.
Last Updated: February 2026 Documentation Version: 2.1.0