QEMU Quick Boot is an handy QEMU VM launcher rewritten in idiomatic, concise, and modern Go. This is a complete rewrite (hence the v2) of the original D language version, providing the same functionality with improved performance and maintainability.

Q2Boot is a command-line tool that wraps QEMU to provide a streamlined experience for launching virtual machines. It automatically configures common settings like KVM acceleration, virtio drivers, and networking while allowing customization through both configuration files and command-line options.

• Zero-config startup: Works out of the box with sensible defaults
• JSON configuration: Persistent settings via ~/.config/q2boot/config.json
• Graphical and headless modes: GUI or console-only operation
• Snapshot support: Choose whether to persist changes
• Multi-architecture support: Works with x86_64, aarch64, ppc64le, and s390x
• KVM acceleration: Automatic hardware acceleration when available
• SSH-ready networking: Built-in port forwarding for easy access
• Comprehensive testing: Full test suite with >95% coverage
• Modern CLI: Built with Cobra for excellent user experience
• Cross-platform: Compiles to native binaries for multiple platforms

Booting a s390x image (very slow!)

Booting a ppc64le image

# Clone the repository
git clone https://github.com/yourusername/q2boot.git
cd q2boot

# Build the project
make build

# Install system-wide (optional)
make install

Download pre-built binaries from the releases page.

The only required argument is the path to the disk image you want to boot, which can be on local disk or a remote URL. Supported remote protocols: http:// https:// ftp:// smb://

# Launch a VM with a disk image
./build/q2boot /path/to/your/disk.img

# Graphical mode
q2boot disk.img -g

# Custom CPU and RAM settings
q2boot disk.img --cpu 4 --ram 8

# Headless mode with persistent changes
q2boot disk.img -w

# Show command before running
q2boot disk.img --confirm

Q2Boot automatically creates a configuration file at ~/.config/q2boot/config.json on first run:

{
  "arch": "x86_64",
  "cpu": 2,
  "ram_gb": 2,
  "ssh_port": 2222,
  "monitor_port": 0,
  "log_file": "q2boot.log",
  "write_mode": false,
  "graphical": false,
  "confirm": false
}

Configuration values are applied in this order (highest priority first):

1. Command-line arguments
2. Configuration file values
3. Built-in defaults

# Start a development VM with GUI
q2boot ubuntu-dev.img -g -c 4 -r 8

# Quick headless test (changes discarded)
q2boot test-image.img

# Persistent headless server
q2boot server.img -w --ssh-port 2223

For advanced use cases, you can pass custom arguments directly to QEMU using the --qemu-extra (or -e) flag. This is useful for enabling experimental features or using devices not configured by default.

# Pass custom arguments to enable a vhost-user-fs device
q2boot my-vm.img \
  -e '-chardev' \
  -e 'socket,id=char0,path=/tmp/vhost-fs.sock' \
  -e '-device' \
  -e 'vhost-user-fs-pci,chardev=char0,tag=myfs'

With the default configuration, you can SSH into your VM:

ssh -p 2222 user@localhost

For debugging, you can expose the QEMU monitor over a telnet port.

# Expose the monitor on port 4444
q2boot -d my-vm.img --monitor-port 4444

# From another terminal, connect to the monitor
telnet localhost 4444

Monitor the VM's serial console:

tail -f q2boot.log

The Go version is structured around clean, idiomatic Go patterns:

q2boot/
├── cmd/q2boot/          # Main application entry point
├── internal/config/    # Configuration management
├── internal/vm/        # VM implementations
├── Makefile           # Build automation
├── go.mod             # Go module definition
└── README_GO.md       # This file

• Configuration Management: Viper-based settings with JSON persistence
• VM Abstraction: Clean interface-based design for different architectures
• Command Line Interface: Cobra-powered CLI with excellent UX
• Error Handling: Proper Go error handling with meaningful messages
• Testing: Comprehensive test suite with good coverage

Q2Boot generates commands similar to:

qemu-system-x86_64 \
  -M q35 -enable-kvm -cpu host \
  -smp 2 -m 4G \
  -drive file=disk.img,if=virtio,cache=writeback,aio=native,discard=unmap,cache.direct=on \
  -netdev user,id=net0,hostfwd=tcp::2222-:22 \
  -device virtio-net-pci,netdev=net0

# Clone the repository
git clone https://github.com/ilmanzo/q2boot.git
cd q2boot

# Install dependencies
make deps

# Build in debug mode
make build

# Build optimized release
make release

# Cross-compile for multiple platforms
make build-all

• make build - Build the binary
• make release - Build optimized release binary
• make build-all - Cross-compile for multiple platforms
• make test - Run tests
• make test-coverage - Run tests with coverage report
• make fmt - Format code
• make vet - Run go vet
• make lint - Run golangci-lint (if available)
• make clean - Clean build artifacts
• make install - Install to /usr/local/bin
• make help - Show all available targets

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run benchmarks
make benchmark

The project follows Go best practices:

• gofmt for consistent formatting
• go vet for static analysis
• golangci-lint for comprehensive linting
• Comprehensive test coverage
• Clear error messages
• Proper interface design

We welcome contributions! Here's how to get started:

1. Check existing issues first
2. Provide system information (OS, QEMU version, Go version)
3. Include error messages and logs
4. Provide steps to reproduce

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes following Go best practices
4. Add tests for new functionality
5. Ensure all tests pass: make test
6. Update documentation if needed
7. Submit a pull request

• Code Style: Follow standard Go conventions and gofmt
• Testing: Add unit tests for new features and bug fixes
• Documentation: Update README and inline docs for public APIs
• Error Handling: Use proper Go error handling patterns
• Interfaces: Design clean, minimal interfaces

• Linux, macOS, or Windows
• QEMU installed and in PATH
• KVM support (Linux) for hardware acceleration
• guestfs-tools for automatic architecture detection (optional, package may be named libguestfs-tools).
• Sufficient RAM for host + VM requirements

• Go 1.21 or later
• Make (for build automation)
• Git (for version information)

The Go version offers several improvements over the original D implementation:

• Faster startup time
• Lower memory usage
• Better resource management

• Clear separation of concerns
• Interface-based design
• Comprehensive test coverage
• Standard Go project structure

• Better error messages
• Improved CLI with Cobra
• Configuration validation
• Version information

• Standard Go tooling
• Easy cross-compilation
• Automated testing
• Consistent formatting

Q: How does this compare to the original D version? A: The Go version provides the same functionality with better performance, maintainability, and user experience.

Q: Can I run multiple VMs simultaneously? A: Yes, use different SSH ports: q2boot -d vm1.img --ssh-port 2222 and q2boot -d vm2.img --ssh-port 2223

Q: How do I create a disk image? A: Use qemu-img create -f qcow2 disk.img 20G or make create-test-disk for a test image.

Q: What's the difference between snapshot and write mode? A: Snapshot mode (default) discards all changes when the VM exits. Write mode saves changes permanently.

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

• QEMU - The amazing virtualization platform
• Cobra - Excellent CLI framework
• Viper - Configuration management
• Original D language implementation by Andrea Manzini
• Contributors and testers who help improve Q2Boot

Happy virtualizing with Go! 🎉🐹

If you find Q2Boot useful, please consider giving it a ⭐ on GitHub!