VMware vSphere Python SDK

Warnings

• breaking pyVmomi 9.0.0.0 introduced several breaking changes including the removal or replacement of `SoapAdapter` connection classes, aliases like `publicVersions` and `dottedVersions`, and changes to the module paths for `VmomiJSONEncoder`, `templateOf()`, and `ThumbprintMismatchException`.
  Fix: Review the pyVmomi 9.0.0.0 release notes for specific class and alias changes. Update import paths and method calls as detailed in the official documentation or the `imports` section of this registry entry. For example, `pyVmomi.VmomiSupport.VmomiJSONEncoder` moves to `pyVmomi.VmomiJSONEncoder.VmomiJSONEncoder`.
• breaking The `six` dependency has been removed, and the `pyOpenSSL` dependency is now limited to '<24.3.0' in pyVmomi 9.0.0.0 due to breaking changes in pyOpenSSL.
  Fix: Ensure your environment meets the updated dependency requirements. If you were relying on `six` directly, update your code to use Python 3 native constructs. Pin `pyOpenSSL` to a compatible version if issues arise.
• deprecated The `b64token` and `mechanism` parameters for `pyVim.Connect()` and `pyVim.SmartConnect()` have been disabled in pyVmomi 9.0.0.0. They are replaced by `token` and `tokenType`.
  Fix: Update your connection calls to use `token` and `tokenType` parameters for SSO authentication, as described in the official vSphere SDK documentation.
• gotcha Connecting to vCenter or ESXi with untrusted (self-signed) SSL certificates will fail by default in modern Python versions.
  Fix: For development or non-production environments, create an unverified SSL context: `context = ssl._create_unverified_context()` and pass it to `SmartConnect(sslContext=context)`. For production, import and verify the vCenter's SSL certificate.
• gotcha pyVmomi is designed for the vSphere Management API (SOAP-based). For newer vSphere Automation APIs (REST-based), you should use the `VMware vSphere Automation SDK for Python` instead.
  Fix: Determine whether you need to interact with SOAP-based Management APIs or REST-based Automation APIs. If the latter, switch to `vsphere-automation-sdk-python` for appropriate functionality.
• gotcha pyVmomi maintains backward compatibility with the previous four releases of vSphere and its own previous four releases. Using it with significantly older or very new, unsupported vSphere versions may lead to unexpected behavior or missing features.
  Fix: Always check the official pyVmomi compatibility matrix against your vSphere environment version to ensure support and expected behavior.

Install

• pip install --upgrade pyvmomi Latest stable release
• pip install -e ".[sso]" Install with SSO support (from source)

Imports

• SmartConnect

  from pyVim.connect import SmartConnect, Disconnect

  SmartConnectNoSSL is deprecated; it's better to manage SSL context explicitly with SmartConnect.
• vim

  from pyVmomi import vim

• VmomiJSONEncoder

  from pyVmomi.VmomiJSONEncoder import VmomiJSONEncoder

  Path changed in pyvmomi 9.0.0.0.
• templateOf

  from pyVmomi.VmomiJSONEncoder import templateOf

  Path changed in pyvmomi 9.0.0.0.
• ThumbprintMismatchException

  from pyVmomi.Security import ThumbprintMismatchException

  Path changed in pyvmomi 9.0.0.0.

Quickstart

This quickstart demonstrates how to connect to a vCenter Server, retrieve its content, and list all virtual machines using pyVmomi. It includes common practices like handling SSL contexts and using environment variables for credentials.

import ssl
import os
from pyVim.connect import SmartConnect, Disconnect
from pyVmomi import vim

# Environment variables for credentials and host
VCENTER_HOST = os.environ.get('VCENTER_HOST', 'your_vcenter_ip_or_fqdn')
VCENTER_USER = os.environ.get('VCENTER_USER', 'your_username')
VCENTER_PASS = os.environ.get('VCENTER_PASS', 'your_password')

if VCENTER_HOST == 'your_vcenter_ip_or_fqdn' or VCENTER_USER == 'your_username' or VCENTER_PASS == 'your_password':
    print("Please set VCENTER_HOST, VCENTER_USER, and VCENTER_PASS environment variables or update the script.")
    exit(1)

def main():
    service_instance = None
    context = None

    try:
        # Disable SSL certificate verification for labs/testing. NOT recommended for production.
        context = ssl._create_unverified_context()
        
        print(f"Connecting to vCenter: {VCENTER_HOST}...")
        service_instance = SmartConnect(host=VCENTER_HOST,
                                      user=VCENTER_USER,
                                      pwd=VCENTER_PASS,
                                      sslContext=context)
        
        content = service_instance.RetrieveContent()
        print(f"Connected to vCenter: {content.about.fullName}")

        # Retrieve all virtual machines
        container = content.viewManager.CreateContainerView(content.rootFolder, [vim.VirtualMachine], True)
        vms = container.view
        
        print("\nVirtual Machines:")
        if not vms:
            print("No virtual machines found.")
        for vm in vms:
            print(f"  Name: {vm.name}, Power State: {vm.runtime.powerState}")
        
        container.Destroy()

    except Exception as e:
        print(f"Error: {e}")
    finally:
        if service_instance:
            print("Disconnecting from vCenter.")
            Disconnect(service_instance)

if __name__ == '__main__':
    main()