hyper2kvm

API Reference Documentation

Complete API reference for using Hyper2KVM programmatically as a Python library.

🚀 Start Here

📚 Complete References

API Documentation Overview

Quick Reference

File: quick-reference.md

Best for: Quick lookups, copy-paste examples, frequently used APIs

Content:

Use when: You know what you want to do and need syntax quickly

Library API Guide

File: library-api.md

Best for: Understanding API levels, choosing the right abstraction, complete workflows

Content:

Use when: Starting a new project, designing workflows, choosing abstraction level

Complete API Reference

File: API-Reference.md

Best for: Detailed parameter documentation, advanced usage, all available methods

Content:

Use when: Need complete parameter details, advanced features, error handling

VMCraft Platform API

File: vmcraft.md

Best for: Advanced disk manipulation, low-level operations, maximum control

Content:

Use when: Need direct disk access, custom fixers, advanced automation

API Level Comparison

Feature Quick Reference Library API API Reference VMCraft API
Audience All users Library users Library users Advanced users
Depth Essential only Complete Complete Deep technical
Format Code snippets Guide + examples Full docs Full docs
Use Case Quick lookup Learning Development Advanced dev
Size 1 page Complete guide Full reference 30,000+ lines

Getting Started Paths

Path 1: Quick Task (5 minutes)

Goal: Convert a VMDK file to qcow2

  1. Check Quick Reference for basic usage
  2. Copy-paste example code
  3. Run conversion

Path 2: Build an Application (1-2 hours)

Goal: Integrate Hyper2KVM into your application

  1. Read Library API introduction
  2. Choose API level (high/mid/low)
  3. Review usage examples for your scenario
  4. Consult API Reference for parameter details
  5. Implement with error handling

Path 3: Advanced Automation (4-8 hours)

Goal: Build custom VM manipulation workflows

  1. Read Library API for architecture
  2. Study VMCraft API for available methods
  3. Design custom workflow using low-level APIs
  4. Use API Reference for integration points
  5. Refer to Quick Reference for common patterns

Common API Use Cases

Single VM Conversion

Recommended: Library API - Level 1 (High-Level API)

from hyper2kvm.core import convert_vm

result = convert_vm(
    input_path="/path/to/vm.vmdk",
    output_path="/path/to/output.qcow2",
    os_type="linux"
)

Reference: API Reference - Core API section

Batch Migration

Recommended: Library API - Batch Migration APIs

from hyper2kvm.orchestrator import BatchOrchestrator

orchestrator = BatchOrchestrator(
    manifest="migrations.json",
    parallel=4
)
orchestrator.execute()

Reference: API Reference - Orchestrator section

Custom VM Inspection

Recommended: VMCraft API - OS Detection

from hyper2kvm.core.vmcraft.main import VMCraft

g = VMCraft()
g.add_drive_opts('/path/to/disk.vmdk', readonly=True)
g.launch()

roots = g.inspect_os()
for root in roots:
    os_type = g.inspect_get_type(root)
    distro = g.inspect_get_distro(root)
    print(f"Found: {os_type} - {distro}")

g.shutdown()

Reference: Quick Reference - OS Detection

Custom Fixer Implementation

Recommended: VMCraft API - File Operations + Boot Management

from hyper2kvm.core.vmcraft.main import VMCraft

g = VMCraft()
g.add_drive_opts('/path/to/disk.vmdk', readonly=False)
g.launch()

# Custom fstab modification
fstab = g.cat('/etc/fstab')
# ... modify fstab ...
g.write('/etc/fstab', new_fstab)

# Regenerate initramfs
g.command(['dracut', '-f'])

g.shutdown()

Reference: VMCraft API - File Operations, Boot Management

API Feature Matrix

Capability Quick Ref Library API API Ref VMCraft
VM Conversion ✅ Basic ✅ Complete ✅ Complete ❌ N/A
Batch Migration ❌ ✅ Complete ✅ Complete ❌ N/A
OS Detection ✅ Common ✅ Complete ✅ Complete ✅ All 62 APIs
File Operations ✅ Common ✅ Complete ✅ Complete ✅ All 70+ methods
Package Mgmt ✅ Common ✅ Complete ✅ Complete ✅ All 50+ methods
Systemd Mgmt ✅ Common ✅ Complete ✅ Complete ✅ All 52 APIs
Boot Fixing ✅ Common ✅ Complete ✅ Complete ✅ All methods
Network Config ✅ Common ✅ Complete ✅ Complete ✅ All methods
Storage Activation ❌ ❌ ❌ ✅ Complete
Custom Workflows ❌ ✅ Hooks ✅ Hooks ✅ Full control

Documentation Organization

By User Experience Level

Beginner (First time using Hyper2KVM as library):

  1. Start with Library API - Overview and Quick Start
  2. Review Level 1 High-Level API examples
  3. Use Quick Reference for syntax

Intermediate (Building production applications):

  1. Read Library API - All three API levels
  2. Consult API Reference for detailed parameters
  3. Implement error handling and validation

Advanced (Custom automation and workflows):

  1. Study VMCraft API - Architecture and all modules
  2. Use API Reference for integration
  3. Design custom fixers and workflows

By Task Type

Simple Conversion:

Production Migration:

Custom Automation:

Troubleshooting:

Getting Started

Guides

Features

Examples

API Statistics

Total API Surface:

Code Size:

Test Coverage: 100% (114 systemd tests, comprehensive integration tests)

Version Information

API Version: v1.0 VMCraft Version: v9.2 Hyper2KVM Version: v2.1.0 Last Updated: February 2026

Quick Navigation: Documentation Hub Reference Documentation Features
This site is open source. Improve this page.