vmware-fusion-py

A Python wrapper for controlling VMware Fusion virtual machines through the vmrun and vmcli command-line utilities and the vmrest local REST API. Designed for automation, scripting, and programmatic VM management on macOS.

Features

VMware — full vmrun coverage

• Power control: start, stop, reset, suspend, pause, unpause
• Snapshot management: create, delete, list, revert
• Network adapters: list, add, configure, delete
• Port forwarding: create, delete, list
• Guest execution: run programs and scripts, manage processes
• Guest filesystem: copy files, create/delete files and directories, rename, list
• Shared folders: add, remove, enable, disable, set state
• Guest interaction: type keystrokes, capture screenshots, read/write variables
• VM lifecycle: clone, delete, upgrade, install/check VMware Tools

VMwareCLI — full vmcli coverage

• Create new VMs with configurable guest OS type
• Chipset: set vCPU count, memory size, cores per socket, simultaneous threads
• Disk: create, extend, move, branch disks; connection control
• Ethernet: query adapters, set connection type, network name, security policy
• MKS: set guest resolution, display count, 3D acceleration, VRAM, graphics memory; send key events and sequences; capture screenshots
• ConfigParams: read and write arbitrary VMX configuration entries
• HGFS: fine-grained shared folder control — enable/disable, read/write access, symlink following, host path, guest name
• Tools: install, upgrade, and query VMware Tools state
• VMTemplate: create and deploy VM templates
• VProbes: load, enable, reset VProbes scripts
• Guest ops: ls, mkdir, rm, mv, ps, kill, run, copyFrom, copyTo, env, create temp files and directories
• Power and snapshot control (native vmcli)

VMRest — full vmrest REST API coverage (VMware Fusion Pro 13+)

• VM management: list, get, clone, delete, register
• Power control: on, off, shutdown, suspend, pause, unpause
• Networking: get guest IP, list NIC IPs, manage NIC devices
• Shared folders: list, mount, update, delete
• VM parameters and restriction settings
• Virtual networks: list, create, MAC-to-IP mappings, port forwarding rules
• Typed exception hierarchy for HTTP errors (VMRestAuthError, VMRestNotFoundError, etc.)

Requirements

• Python 3.8+
• VMware Fusion on macOS
• vmrun and vmcli (included with VMware Fusion)
• requests>=2.28 (installed automatically as a dependency)

Installation

pip install vmware-fusion-py

From source:

git clone https://github.com/ahmetmutlugun/vmware-fusion-py
cd vmware-fusion-py
pip install .

Usage

VMware (vmrun)

import shutil
from vmware_fusion_py import VMware

vmrun_path = shutil.which("vmrun")
vm = VMware(
    vmrun_path=vmrun_path,
    host_type="fusion",
    guest_user="username",
    guest_password="password",
    vm_path="/path/to/vm.vmx",
)

# Power
vm.start()
vm.stop()

# Snapshots
vm.snapshot("before-update")
vm.revert_to_snapshot("before-update")

# Guest filesystem
vm.copy_file_from_host_to_guest("/host/file.txt", "/guest/file.txt")
vm.run_program_in_guest("/usr/bin/python3", program_arguments=["/guest/script.py"])

# Processes
result = vm.list_processes_in_guest()
processes = result["processes"]  # {pid: {"owner": ..., "cmd": ...}}

The vm_path can be set at construction time (as above) and is injected automatically into every call, or passed per-call as a keyword argument:

vm = VMware(vmrun_path=vmrun_path)
vm.start(vm_path="/path/to/vm.vmx")

All methods return a dict with at minimum:

VMwareCLI (vmcli)

import shutil
from vmware_fusion_py import VMwareCLI

vmcli = VMwareCLI(
    vmcli_path=shutil.which("vmcli"),
    vm_path="/path/to/vm.vmx",
    guest_user="username",
    guest_password="password",
)

# Create a new VM
vmcli.create_vm(name="myVM", dirpath="~/VMs", guest_type="arm-ubuntu-64")

# Configure hardware
vmcli.set_vcpu_count(4)
vmcli.set_mem_size(8192)
vmcli.set_cores_per_socket(2)

# Display
vmcli.set_guest_resolution(1920, 1080)
vmcli.set_3d_accel(True)
vmcli.set_vram_size(256)

# VMX config
vmcli.set_config_entry("tools.syncTime", "TRUE")
cfg = vmcli.query_config()

# Disk
vmcli.create_disk("/path/disk.vmdk", adapter="lsilogic", size="50GB", disk_type=0)
vmcli.extend_disk("scsi0:0", new_num_sectors=104857600)

# Shared folders (fine-grained)
vmcli.set_share_enabled("myShare", True)
vmcli.set_share_write_access("myShare", True)
vmcli.set_share_follow_symlinks("myShare", False)

# Guest ops
vmcli.guest_ls("/home/user")
vmcli.guest_run("/usr/bin/python3", program_args=["/tmp/script.py"])
vmcli.guest_copy_to("/host/file.txt", "/guest/file.txt")

# Tools
vmcli.upgrade_tools()

# VM templates
vmcli.create_template("/path/template.vmtx", name="myTemplate")
vmcli.deploy_template("/path/template.vmtx")

# VProbes
vmcli.set_vprobes_enabled(True)
vmcli.load_vprobes("/path/script.vp")

VMRest (vmrest REST API)

First-time setup and server start:

# Configure credentials (≥8 chars, must include lowercase, digit, and special character)
/Applications/VMware\ Fusion.app/Contents/Public/vmrest -C

# Start the server (default: http://127.0.0.1:8697)
/Applications/VMware\ Fusion.app/Contents/Public/vmrest

from vmware_fusion_py import VMRest
from vmware_fusion_py.vmrest import VMRestConnectionError, VMRestNotFoundError

rest = VMRest(username="admin", password="yourpassword")

# List all VMs
vms = rest.vms.list()

# Power control
rest.vms.set_power_state(vm_id, "on")
state = rest.vms.get_power_state(vm_id)

# Networking
ip = rest.vms.get_ip(vm_id)
nics = rest.vms.list_nics(vm_id)

# Shared folders
rest.vms.mount_shared_folder(vm_id, host_path="/host/share", guest_path="myshare")
rest.vms.list_shared_folders(vm_id)

# Virtual networks
nets = rest.network.list_vmnets()
rest.network.update_port_forward(
    "vmnet8", protocol="tcp", port=2222,
    host_ip="127.0.0.1", guest_ip="192.168.1.100", guest_port=22,
)

# Exception handling
try:
    rest.vms.get("nonexistent-id")
except VMRestNotFoundError as exc:
    print(exc.status_code, exc.message)
except VMRestConnectionError:
    print("vmrest is not running")

The VMRest constructor accepts an optional base_url (default http://127.0.0.1:8697) and timeout (default 30.0 seconds).

License

MIT License — see LICENSE.

Contributing

Issues and pull requests are welcome.

Author

Ahmet Mutlugun