pyvmomi: the SOAP binding to vSphere and the four generations it promises to keep working

Why the bindings exist: vSphere SOAP, not the REST automation API

pyvmomi is the Python SDK for the VMware vSphere Management API, the SOAP interface that vCenter Server and ESXi hosts have spoken for years. It binds that interface into Python objects, so inventory walks, power operations and configuration edits become script calls instead of hand-built XML. The reader who benefits is an administrator or developer who already administers an ESXi host or vCenter Server and wants that work scripted; without a vSphere endpoint to talk to, the library does nothing for you.

The boundary is protocol, not preference. Anything reached through the vSphere Automation APIs, which are REST, is pointed at the VMware vSphere Automation SDK for Python instead. That split decides how a migration goes: a script written against SOAP bindings cannot be retargeted at REST endpoints by changing arguments, because the two live in separate packages and expose different call shapes. Settle which side of that line a task sits on before writing the first function.

Two install paths that do not deliver the same code

Two commands cover most installs, and they do not return the same code. One pulls a build published to pypi, described as the official version, while the other builds whatever sits on master, which the README calls code that is in development. A fixed version number comes from the first route; the second hands you the tip of the default branch, where no compatibility window has been established yet.

pip install --upgrade pyvmomi
pip install --upgrade pyvmomi[sso]
pip install ".[sso]"
pip install -e ".[sso]"

Line one is the plain install from pypi and line two adds single sign-on support. Lines three and four build the clone instead, with line four putting it in editable mode so edits to pyVmomi take effect without reinstalling. A script pinned to one version can break after an editable install, because nothing in that install holds the code still. Where reproducibility matters, pin the version you tested against and move up on purpose.

The sso extra is where cryptography and lxml enter

Optional dependencies sit under a single key, sso, and it asks for exactly two packages. Nothing else in the packaging metadata requests them, which means a default install gives you an SDK that can open SOAP sessions but carries nothing for single sign-on.

[project.optional-dependencies]
sso = [
    "cryptography",
    "lxml",
]

This is a runtime boundary, not a cosmetic one. Install `pyvmomi` plainly and the failure arrives later, when the SSO module is imported, rather than at install time when a missing dependency could have been named. Where your estate authenticates through SSO, install the extra before writing the script rather than after the first scheduled job fails.

Where the wheel puts your imports

setuptools builds two packages and two loose modules, and that list is the whole import surface you inherit.

packages = ['pyVmomi', 'pyVim']
py-modules = ['vsanapiutils', 'vsanmgmtObjects']

Both package names are importable exactly as written, and the two module names sit outside any package, so they arrive unnamespaced and can collide with a file of the same name sitting in your script directory. Package data for pyVmomi is declared as every `*.pyi` stub plus `py.typed`, so type information ships inside the wheel rather than arriving from a stub package maintained elsewhere. One oddity: the platform list names Linux, Mac OS-X, Solaris, Windows and Unix, while the operating system classifiers name Windows, POSIX, Unix and MacOS and leave Solaris out entirely.

Four vSphere generations behind a yearly tag cadence

The compatibility policy promises minimum backward compatibility with the previous four releases of vSphere and with pyvmomi's own previous four, while older combinations may keep working without support. Three visible tags carry the dates 2024-06-26, 2025-06-17 and 2026-06-22, roughly a year apart, so four back means about four years. That arithmetic is why a fresh install can still be expected to talk to a vSphere line older than the newest tag. The worked example in the README spells it out: v6.0.0 is most compatible with vSphere 6.0, 5.5, 5.1 and 5.0.

For anyone planning an upgrade the breadth cuts both ways. A four generation window protects a script written years ago, and it also keeps the binding pinned to an interface whose shape was fixed by a vSphere generation predating the current codebase. Every supported generation has to keep working, which is a standing cost for whoever maintains your automation rather than a one-off migration.

The version number has five digits and two owners

pyVmomi versions follow X.Y.Z.U.P, and the README divides the digits between two products: X.Y is the vSphere major version, Z an update, U a patch, and P counts pyvmomi patches stacked on top. Two tag names show both halves at once, since v8.0.3.0.1 carries the label Maintenance Patch 1 for 8.0U3 while its trailing digit counts pyvmomi patches. The later names, v9.0.0.0 and v9.1.0.0, hold the same shape with three digits zeroed, which is how a major version bump looks in this scheme, and both are titled for VCF while the compatibility policy talks only about vSphere.

Where the number comes from matters more than it looks: version is declared dynamic and read from an attribute, pyVmomi.version_info, so the string a client inspects is produced by Python code at packaging time instead of a field an operator edits. Pinning by version after an editable install means checking that attribute in the tree, because pyproject.toml holds no literal version to compare against.

Upgrade cost, support routes and what the README does not cover

The code is packaged under Apache-2.0, which lets you vendor it into a closed product without relicensing your own work, and the last push was on 2026-06-22. Enterprise support is pointed at the SDK and API Support for Commercial and Enterprise Organizations section of the Broadcom Developer Portal, while community questions go to a GitHub issue or a Discussion.

Nothing in the packaging metadata explains how to roll a pinned install back to the version you had before, and the samples the project links live in a separate repository, so any code copied from them is a second dependency to track. Read the digit scheme before planning an upgrade, because whether a newer tag breaks your script depends on which vSphere generation you are on rather than on how recent the tag looks.

What sits at the top of the tree and what reaches the wheel

The repository root is short: NOTICE.txt, MANIFEST.in, README.rst, pyproject.toml, two package directories, a tests directory, and the two loose modules vsanapiutils.py and vsanmgmtObjects.py. The wheel and the tree differ in one visible way, since the packaging metadata lists exactly those two packages and two modules and nothing else, so any name your script imports from this project has to be one of those four.

tests/ is the other half of that arrangement. Running the suite through `tox` expects several Python interpreters on the machine, because the environments are spread across interpreters rather than confined to one.

tox -e py314

That flag limits a run to Python 3.14 when the rest are missing. Note the split configuration: the README tells you to configure interpreters listed in `tox.ini`, while the repository also carries a tox section inside pyproject.toml, so environment settings are not confined to the one file. Contributors are pointed at open issues and a wiki page of contribution standards first.

Editorial conclusion

pyvmomi earns a place in any shop that already administers vCenter Server from Python, and it has no place on the REST side, where the vSphere Automation SDK for Python is the documented answer. Verify three things first: that your interpreter is 3.10 or newer, that the tag you pin matches the vSphere generation you run, and that any script signing in through SSO is installed with the sso extra. Then read pyVmomi.version_info in the tree, because the version string lives in code rather than in pyproject.toml.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. vmware/pyvmomi on GitHub