Skip to main content

Preview a GRUB 2.x theme using KVM/QEMU

Project description


grub2-theme-preview came into life when I was looking around for available GRUB 2.x themes and wanted a way to quickly see a theme in action without rebooting real hardware.

It takes a theme folder (or just a single picture), creates a temporary bootable image using grub2-mkrescue and launches that image in a virtual machine using KVM/QEMU, all without root privileges.

grub2-theme-preview showing theme "gutsblack-archlinux"

(Showing theme gutsblack-archlinux)


To install the latest release from PyPI:

# pip install --user grub2-theme-preview

To install from a Git clone for development:

# pip install --user --editable .

Please make sure to install these non-PyPI dependencies as well:

  • grub-mkrescue of GRUB 2 (package grub-common on Debian and Ubuntu)
  • QEMUhypervisor that performs hardware virtualization
  • OVMF — EFI bios image for use with QEMU
  • mtoolscollection of utilities to access MS-DOS
  • xorriso of libisoburnfrontend which enables creation and expansion of the ISO format


# grub2-theme-preview --help
usage: grub2-theme-preview [-h] [--grub-cfg PATH] [--verbose]
                           [--resolution WxH] [--timeout SECONDS]
                           [--add TARGET=/SOURCE] [--version]
                           [--grub2-mkrescue COMMAND] [--qemu COMMAND]
                           [--xorriso COMMAND] [--no-kvm] [--debug]

positional arguments:
  PATH                  path of theme directory (or PNG/TGA image file) to

optional arguments:
  -h, --help            show this help message and exit
  --grub-cfg PATH       path of custom grub.cfg file to use (default:
  --verbose             increase verbosity
  --resolution WxH      set a custom resolution, e.g. 800x600
  --timeout SECONDS     set GRUB timeout in whole seconds or -1 to disable
                        (default: 30 seconds)
  --add TARGET=/SOURCE  make grub2-mkrescue add file(s) from /SOURCE to
                        /TARGET in the rescue image (can be passed multiple
  --version             show program's version number and exit

command location arguments:
  --grub2-mkrescue COMMAND
                        grub2-mkrescue command (default: auto-detect)
  --qemu COMMAND        KVM/QEMU command (default: qemu-system-<machine>)
  --xorriso COMMAND     xorriso command (default: xorriso)

arguments related to invokation of QEMU/KVM:
  --display DISPLAY     pass "-display DISPLAY" to QEMU, see "man qemu" for
                        details (default: use QEMU's default display)
  --full-screen         pass "-full-screen" to QEMU
  --no-kvm              do not pass -enable-kvm to QEMU (and hence fall back
                        to acceleration "tcg" which is significantly slower
                        than KVM)
  --vga CARD            pass "-vga CARD" to QEMU, see "man qemu" for details
                        (default: use QEMU's default VGA card)

debugging arguments:
  --debug               enable debugging output
  --plain-rescue-image  use unprocessed GRUB rescue image with no theme
                        patched in; useful for checking if a plain GRUB rescue
                        image shows up a GRUB shell, successfully.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

grub2-theme-preview-2.7.0.tar.gz (207.2 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page