Building A Hyper-V Windows 10 Vagrant Box

What Is Wrong With Virtualbox and VMWare?

I am a strong believer of virtualizing everything. So much that all of my development is done on virtual machines. The power of computers these days makes this experience extremely performant and the tooling around it has matured to a level that simplifies the process greatly.

Up until recently, I have been using a combination of Packer, Vagrant, and Virtualbox to get the job done. Of which has produced an experience in which I have next to no complaints about.

So why am I switching to Hyper-V? Well, plain and simple, I am Windows developer. Meaning, I do all my development work on a Windows machine. Of which, without Hyper-V installed, I would not be able to do the following.

  • Work with Docker on Windows.
  • Use the built in emulators supplied by Visual Studio.

Seeing that running Hyper-V side-by-side with Virtualbox or VMWare is impossible to do with any sense of sanity, I said goodbye to VirtualBox and hello to Hyper-V. Following I will outline the process I used to create a Hyper-V Windows 10 Vagrant Box.

For more info on how I create my Windows development environment, be sure to visit Creating a Windows Development Environment With Packer, Vagrant & Chocolatey.

Installing Hyper-V

To start, we need to install Hyper-V.

  1. Ensure that hardware virtualization is supported on your computer and turned on in the BIOS settings.
    • To accomplish this, boot to your bios and enable the "Virtualization Technology" switch.
  2. Head on over to the "Turn Windows features on and off" settings and enable Hyper-V.
    Installing Hyper-V

At this point, you will be informed that a reboot will take place. Once rebooted, Hyper-V will be installed and ready to do.

Building Your Windows 10 VM

On to the fun stuff, building our actual Hyper-V Box of Windows 10. Normally I would use Packer to automate this entire process. This time I decided to not follow suit and instead build it manually. For one, I wanted to use this as a learning experience to understand what actually makes up a Box. In addition, official Hyper-V support with Packer is very new. Meaning, documentation and relevant examples are sparse.

That being said, I trust that once you actually go through the process of building a Box manually once, you will quickly realize much like myself that it is as simple as can be.

Configuring A Network In Hyper-V

The first thing we need to do is create a virtual switch in which we can use to connect our VM to the internet.

  1. Open up your Hyper-V manager and select the "Virtual Switch Manager" option located in the "Actions Pane".
  2. Once open, create a new Switch and configure it like so...
    Hyper-V Switch

Installing Windows 10

Once your Virtual Switch has been created, you can start the process of installing creating a Windows 10 VM.

  1. Initiate a new VM creation from the Hyper-V Manager.
    Hyper-V Switch
  2. You will be guided through a list of screens in which you can use to configure your VM.
    1. Specify a name for your VM and location.
    2. Select a "Generation 2" type when prompted.
    3. Assign enough memory to operate you VM. A recommended safe starting point would be 4 gigs.
    4. When prompted to assign a network, assign the network that we created in our previous steps.
    5. When prompted to supply a Virtual Disk size, I went with 40 gigs. Of which can be expanded at any time after creation.
    6. On the Installation Options screen, target your Windows 10 .ISO to load on boot.
  3. After completing the initial configuration screens, you will enter the normal boot sequence associated with Windows 10. Follow all the normal Windows 10 install prompts until you have a fully installed version of Windows 10 on your new VM.

Configuring Your VM To Be Vagrant Ready

Once you have a fully functional Window 10 VM inside your instance of Hyper-V, you now have to prepare the VM to be exported as a Vagrant Box. There are few goals we want to keep in mind as we go through this process.

  • We want to ensure we are producing...
    • A Box that Vagrant can talk to.
    • A Box that has any and all necessary software installed, based on your needs.
    • A Box that is as small as possible.

Talk To Me

Setting up your VM to be able to communicate is pretty straightforward.

  1. Disabling UAC.
    • Hit the Windows key & type UAC.
    • Select "Change User Account Control Settings".
    • Disable UAC.
      Disable UAC
  2. Switch your network to private.
  3. Configure WinRM (communication pipe between Vagrant and Windows) by running the following commands.
    winrm quickconfig -q
    winrm set winrm/config/winrs @{MaxMemoryPerShellMB="512"}
    winrm set winrm/config @{MaxTimeoutms="1800000"}
    winrm set winrm/config/service @{AllowUnencrypted="true"}
    winrm set winrm/config/service/auth @{Basic="true"}
    sc config WinRM start= auto

What Software Should I Install?

This is highly dependent on the goals you have for your Box. Personally, I take the following approach.

  • Install as little software as possible.
    • This helps keep my Box as small as possible. Of which, I store on Dropbox. By doing so, I eliminate the need to sync a large Box on any new machines I am using for development.
    • All software needed for my dev environment is installed during provisioning of a new VM.
    • For more information on how to do this, you can visit my Pioneer Code Windows Development Environment GitHub repository.
  • Install Chocolatey to assist with provisions. If you don't know what Chocolatey is yet, I recommend it highly and urge you to try it out.

What About Turning Those 1(s) to 0(s)?

The last few steps we need to take will allow us to package our Box in a manner that will produce the smallest footprint possible.

  • Defrag your VM.
    • Hit the **windows** key, type "defrag" and run the native windows defragmentation tool. Defrag
    • Defragging your disk will allow the next step to complete as efficient as possible.
  • Run sDelete to flip all unused bits to zero.
    • If you installed Chocolatey, simply run the following command to install sDelete.
      choco install sdelete
    • If you have not installed Chocolatey, download sDelete at this link.
    • Once installed, run the following command against the sDelete executable.
      sdelete.exe -z c
    • This process will take a while to complete. Often in the range of 30 to 60 mins. It is also worth noting that sDelete at some point will appear to be stuck or frozen while reporting 100%. When you get to the point, do not terminate the process. Instead, be patient and wait it out. Eventually, sDelete will report back a completed status.

Building Your Hyper-V Box

Now that we have configured and created our VM, we can move to building our actual Vagrant Box.

Exporting Your Hyper-V VM

Right-click your VM in the Hyper-V manager and select "Export".

Export VM

Specify a location and hit export.

Export VM Location

Building Your Folder Structure

The Export process will take a couple of minutes and once done, you will end up with a folder structure like so.

Exported folder structure

Adding Vagrant metadata.json

Delete the "Snapshots" folder and add a metadata.json file.

New folder structure

The metadata.json is used by Vagrant to understand what your box is made up of. Open your new metadata.json file and add the following to get started with.

  "provider": "hyperv"

This basic configuration will be enough to build a functioning Box but if you are interested in what else can be added, you can check out the official Box File Format documentation.

Packaging Your Box

A Box File is a compressed file of the type tar, tar.gz, or zip. Out of the three options, a tar.gz will often produce the best compression rate.

To start the process, ensure you have 7Zip installed. Again, you can download it directly from the 7Zip site or install it with Chocolatey.

choco install 7zip.install

Once installed, create a tar file with 7zip.

Create tar file

This process will take a few minutes. Once complete, gzip your new tar file in 7Zip. Depending on the "Compression level" you choose, the time to completion will vary. For reference, when I ran "Ultra", it was measurable in hours.

GZip tar file

Though not needed, once complete, you can strip the tar.gz extension and replace it with .box.

Vagrant Up

The building of your new Box File is complete. To test it we need to first add your new Box to Vagrant. Open up a command prompt and run the following command.

vagrant box add {name-of-box} {}

Navigate to your VagarntFile directory and run the following.

vagrant up --provider hyperv


Setting up a VagrantFile is a whole topic in itself. Luckily for you, I have already done the grunt work and provided a fully functioning VagarntFile at Pioneer Code Windows Development Environment.


And that is that. You know should be in the position to create Hyper-V Windows 10 VMs using a pre-configured Box File. If you have any question, be sure to let me know in the comments section below.