Skip to content

Building VirtualBox

Sorecchione07435 edited this page Nov 9, 2026 · 11 revisions

Building from Source

This guide explains how to compile the custom VNC-enabled VirtualBox build on Windows using Microsoft Visual Studio 2022, KMK, and PowerShell.

Before starting, make sure you have completed the steps described in:

1. Prepare the build environment

Make sure the required build tools and dependencies are installed and configured.

In particular, verify that:

  • Visual Studio 2022 and the required C++ components are installed.
  • The Windows SDK and WDK are available.
  • Python, Qt, Yasm/NASM, and the other required tools are configured.
  • The LocalConfig.kmk file contains the correct paths and build options.
  • The libvncserver dependency is available if required by your source configuration.

Tip

Start PowerShell from the Visual Studio 2022 x64 Native Tools environment, so that the appropriate MSVC compiler and linker tools are available.

2. Get the VirtualBox source code

There are three ways to obtain the source code. Choose one.

Option A: Clone the official repository with Git

git clone https://github.com/VirtualBox/virtualbox.git C:\Dev\virtualbox

With this option you must build libvncserver yourself and apply the source modifications described in section 5.

Option B: Use the repository of this wiki (recommended)

The repository this wiki belongs to already contains the source tree with the libvncserver library precompiled and all the VNC source modifications applied. It is ready to be compiled without any changes.

git clone https://github.com/St3vSoft/VirtualBox-VNC-Windows.git C:\Dev\virtualbox

Note

If you use this option, you can skip section 5 and the Building libvncserver guide, and go directly to section 6.

Option C: Download the source from the official VirtualBox website

  1. Download the source code archive from the official VirtualBox Downloads page.
  2. Extract it to your working directory, for example C:\Dev\virtualbox, using a tool such as 7-Zip.

As with Option A, you must build libvncserver yourself and apply the source modifications described in section 5.

Tip

Keep the path of the source tree short and free of spaces, to avoid problems with the build tools.

3. Configure PowerShell environment variables

Set the kBuild directory and add its executable directory to the PATH environment variable.

Example:

$env:KBUILD_PATH = "C:\Dev\virtualbox\kBuild\kBuild"

$env:PATH = "C:\Dev\virtualbox\kBuild\kBuild\bin\win.amd64;" + $env:PATH

Adjust these paths to match your local source tree and kBuild installation.

You can verify that KMK is accessible with:

Get-Command kmk.exe

Note

Variables set with $env: apply only to the current PowerShell session. If you open a new PowerShell window, you must configure them again.

4. Navigate to the VirtualBox source directory

Change the current directory to the root of your VirtualBox source tree.

cd C:\Dev\virtualbox

Make sure you are running the command from the correct source directory.

5. Apply the required source modifications

Before compiling VirtualBox, two modifications must be applied to the VNC extension source files.

5.1. Modify VBoxVNC.cpp

Open the following file:

virtualbox\src\VBox\ExtPacks\VNC\VBoxVNC.cpp

Add the following header includes at the beginning of the file, alongside the other system headers:

#include <winsock2.h>
#include <ws2tcpip.h>
#include <windows.h>

Important

winsock2.h must be included before windows.h, otherwise the legacy Winsock definitions pulled in by windows.h will conflict with it.

These headers provide the Windows API and Winsock declarations required by the VNC implementation.

Save the modified file before proceeding.

5.2. Modify Makefile.kmk

Open the following file:

virtualbox\src\VBox\ExtPacks\VNC\Makefile.kmk

Locate the existing definitions of the following variables:

  • VBoxVNC_INCS
  • VBoxVNC_LIBS
  • VBoxVNC_DEFS

Replace their existing definitions with the following lines:

VBoxVNC_INCS = VNCBuild/install/include
VBoxVNC_LIBS = VNCBuild/install/lib/vncserver.lib ws2_32.lib
VBoxVNC_DEFS =

Note

The path VNCBuild/install/lib/vncserver.lib is only an example. Make sure it points to the actual location of the vncserver.lib generated during the LibVNCServer build. If LibVNCServer was installed elsewhere, update both the include and library paths accordingly.

The ws2_32.lib entry links the Windows Winsock library, which is required for network communication.

Save the modified Makefile.kmk before proceeding with the VirtualBox compilation.

5.3. Verify the modifications

Before proceeding, verify that:

  1. VBoxVNC.cpp contains all three Windows headers in the correct order.
  2. Makefile.kmk contains the updated definitions, replacing the previous ones.
  3. The include directory points to the compiled LibVNCServer headers.
  4. The library path points to the actual compiled vncserver.lib file.
  5. ws2_32.lib is included in the linker dependencies.

Once both files have been modified and saved, proceed with the VirtualBox compilation.

6. Install the Mako Python package

The VirtualBox build system requires Mako, a Python-based template engine used during the source generation and compilation process.

Install Mako in your local system Python environment using PowerShell:

python -m pip install Mako

To verify that the package is installed correctly, run:

python -m pip show Mako

Important

Mako must be installed in the same Python environment used by the VirtualBox build system, otherwise the build will not find it.

7. Start the compilation

Once the environment is configured, the source modifications have been applied, and Mako is installed, you can start compiling VirtualBox.

Run KMK using the following command:

kmk.exe -k -j 8

This starts the VirtualBox build with up to eight parallel jobs.

KMK command-line options

Option Description
-k Continue building other targets when an error occurs, where possible.
-j 8 Run up to eight build jobs in parallel.

Adjusting the number of parallel jobs

The number after -j can be changed according to your system's available CPU and memory resources.

For example, to use 12 parallel jobs:

kmk.exe -k -j 12

Note

The -j value is the number of parallel build jobs, not the number of physical CPU cores. More jobs can speed up compilation, but also increase CPU and memory usage.

8. Check the build result

Wait for KMK to finish compiling the requested targets.

If the build completes successfully, the generated binaries and VNC Extension Pack will be available in the corresponding build output directories.

If compilation fails, review the error messages in the PowerShell output and check the relevant configuration, dependencies, and toolchain versions.

Tip

For known problems and possible workarounds, see Common Issues.

Additional notes

Caution

Do not distribute your private code-signing certificate or private key.

Warning

This is an unofficial custom build of VirtualBox and is not supported or endorsed by Oracle

Warning

Do not install the official Oracle VirtualBox Extension Pack on this build.

This build compiles the EHCI (USB 2.0) and xHCI (USB 3.0) controllers directly into VBoxDD. The official Extension Pack registers the same USB devices, which causes a PDM name clash when a VM starts:

Driver name clash. Another driver with the same name as the one being registered exists. (VERR_PDM_USB_NAME_CLASH)
E_FAIL (0x80004005)

As a result, virtual machines will fail to start with a "Power VM up" error.

  • USB 2.0 and USB 3.0 are already included in this build, so the Oracle pack is not needed for them.

  • The Oracle pack is a closed-source binary (PUEL license) intended for official builds only, and is not supported on custom OSE builds.

  • If you already installed it, remove it with:

    VBoxManage extpack uninstall "Oracle VM VirtualBox Extension Pack"
    VBoxManage extpack cleanup

Not available in this build: VRDP, disk image encryption, webcam passthrough and Intel PXE boot ROM, which are provided only by the official Extension Pack. Use the included VNC Extension Pack for remote display (VBoxManage modifyvm <vm> --vrde on --vrde-ext-pack VNC).