How to Change VMX Programmatically?

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.

Bothered by SLOW Web UI to manage vSphere? Want to manage ALL your VMware vCenters, AWS, Azure, Openstack, container behind a SINGLE pane of glass? Want to search, analyze, report, visualize VMs, hosts, networks, datastores, events as easily as Google the Web? Find out more about vSearch 3.0: the search engine for all your private and public clouds.

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.

This entry was posted in vSphere API and tagged , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.


  1. Peter Lauterbach
    Posted May 30, 2012 at 8:38 am | Permalink

    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. Posted May 30, 2012 at 10:47 am | Permalink

    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
    Posted May 30, 2012 at 11:21 am | Permalink

    @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
    Posted December 19, 2014 at 10:19 am | Permalink

    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. Posted December 27, 2014 at 2:48 pm | Permalink

    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
    Posted December 30, 2014 at 11:16 am | Permalink

    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. Posted December 30, 2014 at 12:46 pm | Permalink

    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!

2 Trackbacks

Post a Comment

Your email is never published nor shared. Required fields are marked *


You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>


    My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.