VirtualBox* is a type 2 hypervisor from Oracle. This document explains how to create a virtual machine on the VirtualBox hypervisor with Clear Linux* OS as the guest operating system.

These instructions make use of a preinstalled Clear Linux OS disk image to setup a Clear Linux OS virtual machine without manual installation. Clear Linux OS can also be installed from scratch on a VirtualBox using the Clear Linux OS installed. See: Install Clear Linux* OS as a VirtualBox* Virtual Machine


Before continuing make sure that you have:

  1. Enabled virtualization, such as Intel® Virtualization Technology (Intel® VT), on the host system from EFI/BIOS.
  2. Downloaded and installed VirtualBox version 6.0 or greater from the official VirtualBox website per the appropriate instructions for your platform.

Download and extract Clear Linux OS

The Clear Linux OS live image needs to be downloaded and extracted. The live image will be used to created a VirtualBox virtual disk image that can be used with a VM.

  1. Download the live image (clear-<VERSION-live.img.xz) of Clear Linux OS. On the downloads page, this is listed as Clear Linux OS live boot image.

    You can also use this command to download from a terminal:

    curl -O$(curl | grep live.img)
  2. Validate the integrity of the downloaded image by checking the file hash and signatures. Refer to the document on Validate signatures for detailed steps.

  3. Decompress the downloaded image. Uncompressed image size is ~ 5GB.

    • On Windows you can use 7zip to extract the file by right-clicking the file and selecting Extract Here (in the same directory)

      7zip extract here command
    • On Linux :

      xz -d clear-<VERSION>-live.img.xz
  4. There originally downloaded compressed archive file (clear-<VERSION>-live.img.xz) can now be deleted.

Convert Clear Linux OS live image to a VirtualBox Disk Image

The Clear Linux OS live image is in a RAW disk image. The live image needs to be converted to a VDI format which VirtualBox can utilize.

  1. Launch a terminal and navigate to the directory containing the extracted live image.

  2. Convert RAW live image to a VDI format using the command-line VirtualBox Disk Utility.

    VBoxManage convertfromraw clear-<VERSION>-live.img clear-VM.vdi --format VDI


    The PATH environment variable may need to be updated to make the VBoxManage command easily accessible from the terminal. For example, using Windows PowerShell:

    $env:PATH += ";C:\Program Files\Oracle\VirtualBox"
    Convert image in Windows command prompt

    For more information on the VBoxManage command, see the VirtualBox manual section on VBoxManage.

  3. The originally extracted live image file (clear-<VERSION>-live.img) can now be deleted.

  4. Move the converted clear-VM.vdi disk image file to a permanent location. The VDI will be attached to the VirtualBox VM and should not be deleted.

Create a new VirtualBox virtual machine

A new VM needs to be created in VirtualBox Manager to attach the VDI with Clear Linux OS installed.

General instructions for creating a virtual machine and details about using different settings are available on the VirtualBox manual section on Creating a VM.

  1. Launch the VirtualBox Manager from your host system.

  2. Click the New button to create a new VM.

    Create a new VM in VirtualBox
  3. A Create Virtual Machine window will appear. Select the following settings:

    • Type: Linux
    • Version: Linux 2.6 / 3.x / 4.x (64-bit)
    • Memory size: 1024 MB (this can be adjusted appropriately)
    • Hard disk: Use an existing virtual hard disk file

    Click the folder icon next to the drop down menu:

    Create a new VM in VirtualBox with an existing disk
  4. A new window will appear for choosing an existing disk. Click the Add button, browse to the saved VDI file, and click Choose.

    Create a new VM in VirtualBox with an existing disk
  5. Click the Create button.

  6. A new virtual machine will be created and appear in the VirtualBox Manager. Click Settings to configure the Clear Linux OS VM.

    A VM selected in VirtualBox Manager
  7. A VM - Settings window will appear. Navigate to the System pane from the left-hand and select the following setting:

    • Enable I/O APIC
    • Enable EFI (special OSes only)
    Enable EFI on a VirtualBox VM settings


By default, only 1 virtual CPU is allocated to the new VM. Consider increasing the number of virtual processors allocated to the virtual machine under Settings –> System –> Processor for increased performance.

Start the Clear Linux OS VM

The Clear Linux OS VM can now be powered on and setup.

General instructions for using a VirtualBox virtual machine are available on the VirtualBox manual section on Running a VM.

  1. Start the VM from the VirtualBox Manager by selecting the Clear Linux OS VM and clicking Start

    Starting a VirtualBox VM
  2. Clear Linux OS will boot and prompt for login.

    • Enter root for the username.
  3. You will be immediately prompted to set a new password for the root user. Reference OS Security for more information about Clear Linux OS security concepts.

    Initial login to Clear Linux OS on a VirtualBox VM

Install VirtualBox Linux Guest Additions

The VirtualBox Linux Guest Additions provide drivers for full compatibility and functionality.

Clear Linux OS provides VirtualBox guest drivers and an install script in the kernel-lts (Long Term Support) bundle by Clear Linux OS.

  1. Validate the installed kernel is kernel-lts by checking the output of the uname -r command. It should end in .lts.

    uname -r

    If the running kernel is not lts: install the LTS kernel manually, update the bootloader, and check again:

    swupd bundle-add kernel-lts
    clr-boot-manager set-kernel $(basename $(realpath /usr/lib/kernel/default-lts))
    clr-boot-manager update
  2. Remove any kernel bundles that are not kernel-lts or kernel-install to simplify and avoid conflicts:

    swupd bundle-list | grep kernel
    swupd bundle-remove <NON-LTS-KERNEL>
    Initial login to Clear Linux OS on a VirtualBox VM
  3. From the VM Console window, click Devices on the top menu bar, and select Insert Guest Additions CD image... to mount the VirtualBox driver installation to the Clear Linux OS VM.

    VirtualBox CD


To release the mouse cursor from the VM console window, press the right Ctrl key on the keyboard.

  1. Clear Linux OS provides a script called install-vbox-lga to help patch and install VirtualBox drivers for Clear Linux OS. Inside Clear Linux OS VM run this command:

  2. After the script completes successfully, reboot the Clear Linux OS VM.

  3. After the VM reboot, login and verify the VirtualBox drivers are loaded:

    lsmod | grep ^vbox

    You should see drivers loaded with names beginning with vbox: (vboxguest, vboxsf, vboxvideo).

The Clear Linux OS VM running on VirtualBox is ready to be used.


  1. Problem: Out of disk space inside of Clear Linux OS and not be able to install additional bundles.

    Solution: The Clear Linux OS images are small to minimize download time and initial disk space .

    Power off the VM and resize the virtual disk for the Clear Linux OS VM using the VirtualBox Virtual Media Manager found under the File menu. Afterwards, power the Clear Linux OS VM on and follow the instructions here to have Clear Linux OS detect the resized disk. Increase virtual disk size of a Clear Linux* OS image

  2. Problem: On a Microsoft Windows OS, VirtualBox encounters an error when trying to start a VM indicating VT-X/AMD-v hardware acceleration is not available on your system.

    VirtualBox hardware acceleration error

    Solution: First, double check the Prerequisites section to make sure Hardware accelerated virtualization extensions have been enabled in the host system’s EFI/BIOS.

    Hardware accelerated virtualization, may get disabled for VirtualBox when another hypervisor, such as Hyper-V is enabled.

    To disable Hyper-V execute this command in an Administrator: Command Prompt or Powershell, and reboot the system:

    bcdedit /set {current} hypervisorlaunchtype off

    To enable Hyper-V again, execute this command in an Administrator: Command Prompt or Powershell, and reboot the system:

    bcdedit /set {current} hypervisorlaunchtype Auto