Home > vSphere API > How to Change VMX Programmatically?

How to Change VMX Programmatically?

January 31st, 2011 Leave a comment Go to comments

As most of you may have known, the vmx file is the most important file at the back of a virtual machine. It defines the configurations of a virtual machine for example virtual hardware version, devices, disk files, etc. That is why it owns the virtual machine icon when you look at all the files behind a virtual machine with either datastore browser in vSphere Client or VMware Workstation/Fusion.

Given the importance of the vmx file, we don’t recommend anyone to manually modify it given that messing it up may corrupt a virtual machine. You can change the content indirectly from GUI and APIs. If you can change the virtual devices of a virtual machine, its vmx file is changed accordingly.

Time to learn how to "Google" and manage your VMware and clouds in a fast and secure


Beyond basic configuration entries, the vmx file can be extended to hold key/value pairs. A vmx file is really a text file with many lines of key/value pairs. By extending it, you can add extra lines of key/value pairs at the end of the file. Keep in mind that you should NOT add any key that is duplicated with predefined keys like “virtualHW.version.” As you already noticed, the key has the “.” delimiter as namespace pattern. You can start with your own namespace to avoid possible name clash.

With the extensibility of vmx file, many do leverage the vmx file as an easy way to save additional configuration data. Some people even go further by saving their own application specific data. I do not recommend the latter practice because that is the intended use case.

As mentioned, we don’t recommend manual modification. In the following, we are going to discuss how you can change vmx via the vSphere API. If you have read Carter Shanklin’s PowerCLI blog, you probably have a good idea on how to do it with PowerShell on the extended key/value pair. Here we are going to discuss it in the context of general vSphere API and show you a sample built with VI Java API.

First, let’s see how you can get the content of the vmx file. It depends on the nature of the key/value pair. For the device related information, you can find it with a VirtualMachine object’s “config.hardware” property. For the extended key/value pair, you can find it in the “config.extraConfig” property, which is an array of OptionValue objects. Each of the OptionValue object holds a key/value pair. If you are using VI Java API, it’s as simple as the following line:

OptionValue[] ovs = (OptionValue[]) vm.getPropertyByPath("config.extraConfig");

Secondly, let’s see how to change the vmx file. For the non extended part, you don’t change the key/value pair directly but rather change the device configuration for example. For the extended part, you can change it with the reconfigVM_Task() method as shown in below:

VirtualMachineConfigSpec vms = new VirtualMachineConfigSpec();
vms.extraConfig = <strong>new</strong> OptionValue[] { <em>newOptionValue</em>(<em>“key”</em>, "value")};

Note that I just make up the key and value. In reality, you should find out the real key you want to change. There are many examples in the vSphere 4.1 Security Hardening Guide (check out the guidelines whose codes starts with VMX) and William Lam’s blog on his famous reporting script.

I will post a full sample after my PEX 2011 talk in two weeks. Stay tuned.

  1. Peter Lauterbach
    May 30th, 2012 at 08:38 | #1

    It looks like the code examples have markup in the, is this markup really part of the code?

    VirtualMachineConfigSpec vms = new VirtualMachineConfigSpec();
    vms.extraConfig = new OptionValue[] { newOptionValue(“key”, “value”)};

  2. May 30th, 2012 at 10:47 | #2

    Hi Peter,
    It seems some HTML tags got into the code snippet. I think your version is perfect. Thanks for pointing it out!

  3. Peter Lauterbach
    May 30th, 2012 at 11:21 | #3

    @Steve Jin

    Odd. All I did was cut n paste the version with markup into the comment. It seems to render fine in the comment bubble, but not in the code window.

  4. Hamed
    December 19th, 2014 at 10:19 | #4

    Hi steve
    thank you for this post
    in vmware ESXI 5 virtualHW version by default is 10
    so we can not customize it with Vsphere Client (with out Vcenter)
    how can we set virtualHW version to 8 when we want to create VM?
    or how can we change virtualHW version in vm VMX ?

  5. December 27th, 2014 at 14:48 | #5

    Customization feature requires vCenter which VMware makes bigger money than single ESXi. There is a property version in VirtualMachineConfigSpec for creating a new virtual machine. Have you tried it? Good luck.

  6. Hamed
    December 30th, 2014 at 11:16 | #6

    thank you Steve for responding.
    yes I tried “vmSpec.setVersion(“8″);” when I want to create a new VirtualMachine
    but when I run the code I get this error :
    “The operation is not supported on the object.”
    I use Vmware ESXi (without Vcenter)
    Best Regards

  7. December 30th, 2014 at 12:46 | #7

    Hi Hamed, as its name suggests, the error means it’s not supported, on ESXi. You may want to use VMware vCenter for the call. Good luck!

  1. January 31st, 2011 at 01:29 | #1
  2. February 14th, 2011 at 01:53 | #2