hyper2kvm

User Guides

Task-oriented guides for using Hyper2KVM effectively. Learn how to accomplish specific tasks and use various features.

Quick Navigation

🚀 Quick Start Guides

📋 Command-Line Guides

🔄 Migration Guides

🎨 Terminal UI (TUI) Guides

⚙️ Configuration Guides

🔒 Security & Operations

✨ Advanced Features

Guide Categories

By Difficulty

Difficulty Guides Best For
⭐ Beginner Cookbook, CLI Reference, YAML Examples Getting started
⭐⭐ Intermediate Migration Playbooks, Batch Migration, TUI Regular usage
⭐⭐⭐ Advanced Enhanced Features, HyperSDK, Security Power users

By Use Case

Use Case Recommended Guides
First migration Cookbook → CLI Reference
Multiple VMs Batch Migration Features → Batch Quick Reference
Production deployment Security Best Practices → Migration Playbooks
Automation YAML Examples → HyperSDK Quickstart
Troubleshooting Troubleshooting Guide → Cookbook
Interactive work TUI Quickstart → Dashboard Guide

By Task

Task Guide Time
Migrate single VM Cookbook 10 min
Migrate multiple VMs Batch Migration 30 min
Set up automation HyperSDK Quickstart 45 min
Configure CLI CLI Reference 15 min
Use TUI TUI Quickstart 10 min
Troubleshoot issues Troubleshooting Varies
Secure migrations Security Best Practices 30 min

📖 Cookbook

Perfect for: Quick solutions to common tasks

The cookbook provides ready-to-use recipes for:

→ Open Cookbook

🔄 Migration Playbooks

Perfect for: Step-by-step migration workflows

Complete playbooks covering:

→ Open Migration Playbooks

🔒 Security Best Practices

Perfect for: Securing your migration process

Security guidelines for:

→ Open Security Guide

🛠️ Troubleshooting Guide

Perfect for: Fixing common issues

Solutions for:

→ Open Troubleshooting Guide

CLI Reference

Command Categories

Migration Commands:

Worker Commands:

→ Complete CLI Reference

Configuration Formats

command: local
vmdk: /path/to/vm.vmdk
output_dir: /output/path
to_output: converted-vm.qcow2
out_format: qcow2
fstab_mode: stabilize-all
regen_initramfs: true
update_grub: true

Best for: Most use cases, easy to read and maintain

→ YAML Examples

JSON Manifests

{
  "command": "local",
  "vmdk": "/path/to/vm.vmdk",
  "output_dir": "/output/path",
  "to_output": "converted-vm.qcow2"
}

Best for: Automation, programmatic generation

→ YAML vs Manifests Guide

Quick Start Paths

Path 1: First-Time User (30 minutes)

  1. Read Cookbook (10 min)
  2. Try basic migration recipe (15 min)
  3. Review CLI Reference (5 min)

Path 2: Batch Migration (1 hour)

  1. Read Batch Migration Features (20 min)
  2. Create batch manifest (15 min)
  3. Run batch migration (20 min)
  4. Review Batch Quick Reference (5 min)

Path 3: Production Deployment (2 hours)

  1. Review Security Best Practices (30 min)
  2. Read Migration Playbooks (30 min)
  3. Plan migration strategy (30 min)
  4. Execute migrations (30 min)

Path 4: Interactive User (20 minutes)

  1. Read TUI Quickstart (10 min)
  2. Launch TUI dashboard (2 min)
  3. Explore Dashboard Guide (8 min)

Advanced Topics

Automation with HyperSDK

from hypersdk import MigrationClient

client = MigrationClient()
result = client.migrate_vm(
    vmdk="/path/to/vm.vmdk",
    output_dir="/output/path"
)

→ HyperSDK Quickstart

Enhanced Features

→ Enhanced Features Guide

Common Tasks

Task: Migrate a Windows VM

# windows-migration.yaml
command: local
vmdk: /vmware/windows-server-2019.vmdk
output_dir: /kvm/vms
to_output: windows-server-2019.qcow2
windows_drivers: true
fstab_mode: stabilize-all
compress: true

sudo hyper2kvm --config windows-migration.yaml

See: Cookbook

Task: Migrate Multiple VMs

# batch.yaml
command: local
batch_manifest: migrations.json
batch_parallel: 3
output_dir: /kvm/batch

{
  "migrations": [
    {"vmdk": "/vmware/vm1.vmdk", "to_output": "vm1.qcow2"},
    {"vmdk": "/vmware/vm2.vmdk", "to_output": "vm2.qcow2"}
  ]
}

sudo hyper2kvm --config batch.yaml

See: Batch Migration Guide

Task: Fetch from ESXi

# fetch.yaml
command: fetch-and-fix
host: esxi-host.example.com
user: root
identity: ~/.ssh/id_rsa
remote: /vmfs/volumes/datastore1/vm/vm.vmdk
output_dir: /kvm/vms
to_output: migrated-vm.qcow2

sudo hyper2kvm --config fetch.yaml

See: Migration Playbooks

Common Issues

Issue Solution Guide
Boot failure Check bootloader and initramfs Troubleshooting
No network Verify VirtIO drivers Troubleshooting
Permission denied Run with sudo Troubleshooting
Conversion fails Check disk space Troubleshooting
Windows drivers Use –windows-drivers Cookbook

Before Reading Guides

While Using Guides

After Using Guides

Contributing to Guides

Help improve the guides:

  1. Found an issue? Open an issue
  2. Have a recipe? Share it in the Cookbook
  3. Found a workaround? Add to Troubleshooting

See: Contributing Guide

What’s Next?

Choose your path:

🍳 I want quick recipes

→ Start with Cookbook

📋 I want complete reference

→ Read CLI Reference

🔄 I want migration workflows

→ See Migration Playbooks

🎨 I want interactive UI

→ Try TUI Quickstart

🔒 I want security guidance

→ Review Security Best Practices

🛠️ I have a problem

→ Check Troubleshooting Guide

Last Updated: February 2026 Total Guides: 15+ Coverage: CLI, Migration, TUI, Security, Troubleshooting

This site is open source. Improve this page.