VmRun: A Beginner’s Guide to Running Virtual Machines

VmRun: A Beginner’s Guide to Running Virtual MachinesVirtual machines (VMs) let you run entire operating systems inside isolated environments on a host machine. For many users, automating and controlling those VMs from the command line is essential. VmRun (often stylized as vmrun) is a simple, powerful command-line utility included with VMware products (such as VMware Workstation, VMware Fusion, and VMware vSphere/ESXi toolsets) that lets you manage VMs without opening a graphical interface. This guide introduces vmrun, explains common workflows, and gives practical examples so you can start automating VM tasks.

---

What is vmrun?

vmrun is a command-line utility provided by VMware that allows you to perform management operations on virtual machines. It supports actions such as starting and stopping VMs, running programs inside guest operating systems, taking snapshots, and cloning. Because it operates from the command line, vmrun is well-suited for scripting and automation.

Key characteristics:

• Works with VMware Workstation, Fusion, and certain vSphere/ESXi setups.
• Can control VMs both on the host and remotely (depending on product and configuration).
• Supports guest-level operations if VMware Tools are installed in the VM.

---

Prerequisites

Before using vmrun effectively, ensure the following:

• You have a VMware product that includes vmrun (Workstation, Fusion, or certain VMware packages).
• The vmrun binary is on your PATH or you know its full path (common locations: on Windows inside the VMware installation folder; on macOS inside the Fusion app bundle; on Linux inside VMware Workstation directories).
• VMware Tools (or Open VM Tools) are installed inside guest VMs for guest-execution and file operations.
• For remote operations, you have network connectivity and proper credentials to the host or vCenter/ESXi host (if supported by your VMware edition).

---

Basic vmrun syntax

The typical vmrun command structure is:

vmrun [global-options] <command> [command-arguments] 

Common global options include authentication switches when connecting to remote hosts. Many commands require the path to the VM’s configuration file (.vmx) or the URL of a remote VM managed by an ESXi/vCenter instance.

---

Common vmrun commands and examples

Below are the most frequently used vmrun commands with examples.

1. Start a virtual machine

• Power on a VM (GUI/regular start):

  
  vmrun -T ws start "/path/to/VM.vmx" 

• Headless start (no GUI window; useful on servers):

  
  vmrun -T ws start "/path/to/VM.vmx" nogui 

1. Stop a virtual machine

• Graceful guest shutdown (requires VMware Tools):

  
  vmrun -T ws stop "/path/to/VM.vmx" 

• Force power off (equivalent of pulling the plug):

  
  vmrun -T ws stop "/path/to/VM.vmx" hard 

1. Suspend and reset

• Suspend:

  
  vmrun -T ws suspend "/path/to/VM.vmx" 

• Reset:

  
  vmrun -T ws reset "/path/to/VM.vmx" 

1. List running VMs

• On a local host:

  
  vmrun -T ws list 

• Against an ESXi host (example with credentials):

  
  vmrun -T esx -h https://esxi-host/sdk -u username -p password list 

1. Take and manage snapshots

• Take a snapshot:

  
  vmrun -T ws snapshot "/path/to/VM.vmx" "SnapshotName" 

• Revert to a snapshot:

  
  vmrun -T ws revertToSnapshot "/path/to/VM.vmx" "SnapshotName" 

• Delete a snapshot:

  
  vmrun -T ws deleteSnapshot "/path/to/VM.vmx" "SnapshotName" 

1. Run a command inside the guest OS (requires VMware Tools)

• Run an executable on Windows guest:

  
  vmrun -T ws -gu Administrator -gp 'password' runProgramInGuest "/path/to/VM.vmx" "C:\Windows\System32\notepad.exe" 

• Run a shell command on Linux guest:

  
  vmrun -T ws -gu root -gp 'password' runProgramInGuest "/path/to/VM.vmx" "/bin/bash" "-c" "touch /tmp/hello_vmrun" 

1. Copy files between host and guest

• Copy from host to guest:

  
  vmrun -T ws -gu user -gp 'pass' copyFileFromHostToGuest "/path/to/VM.vmx" "/host/path/file.txt" "/guest/path/file.txt" 

• Copy from guest to host:

  
  vmrun -T ws -gu user -gp 'pass' copyFileFromGuestToHost "/path/to/VM.vmx" "/guest/path/file.txt" "/host/path/file.txt" 

1. Check guest OS state and other info

• Get the guest OS type and tools status (some commands):

  
  vmrun -T ws getGuestIPAddress "/path/to/VM.vmx" 

---

Authentication & remote hosts

When managing remote ESXi/vCenter hosts, include the host URL and credentials:

vmrun -T esx -h https://esxi-host/sdk -u root -p 'password' start "[datastore1] folder/VM.vmx" 

Be cautious storing credentials in scripts. Use secure vaults or environment-based protections where possible.

---

Practical scripting examples

1. Start multiple VMs in sequence (bash):

   #!/bin/bash vms=( "/vms/app1/VM.vmx" "/vms/db/VM.vmx" "/vms/cache/VM.vmx" ) for vm in "${vms[@]}"; do vmrun -T ws start "$vm" nogui sleep 5 done 

2. Run a setup script inside a guest after boot:

   vmrun -T ws start "/vms/app/VM.vmx" nogui # wait until VM has an IP (requires VMware Tools) while ! vmrun -T ws getGuestIPAddress "/vms/app/VM.vmx" >/dev/null 2>&1; do sleep 2 done vmrun -T ws -gu admin -gp 'password' runProgramInGuest "/vms/app/VM.vmx" "/bin/bash" "-c" "/home/admin/setup.sh" 

3. Snapshot before risky changes:

   vmrun -T ws snapshot "/vms/test/VM.vmx" "pre-change" # perform change... # revert if needed vmrun -T ws revertToSnapshot "/vms/test/VM.vmx" "pre-change" 

---

Troubleshooting tips

• vmrun requires VMware Tools for many guest-level commands. If runProgramInGuest or file-copy commands fail, verify VMware Tools are installed and running.
• On macOS, vmrun is inside the Fusion app bundle; use the full path or add it to PATH: /Applications/VMware Fusion.app/Contents/Library/vmrun
• Permission errors: on some systems vmrun must be run with elevated privileges (or by the same user that owns the VM files).
• Network/remote errors: confirm ESXi API endpoint (https://host/sdk) and credentials, and that firewall rules permit management traffic.
• Use the verbose output (redirect stderr/stdout) to capture error messages for debugging.

---

Security considerations

• Avoid hard-coding plaintext credentials in scripts. Use environment variables, secure vaults, or interactive prompts.
• Limit access to hosts and VM files by filesystem permissions and network controls.
• Keep VMware Tools and VMware host software updated to reduce security vulnerabilities.

---

Alternatives and when to use vmrun

vmrun is ideal for light automation, quick scripting tasks, and environments using VMware Workstation/Fusion or certain ESXi setups. For larger-scale orchestration, consider:

• VMware PowerCLI (PowerShell), which offers deeper integration with vSphere and richer management features.
• vSphere APIs/SDKs for programmatic control from various languages.
• Configuration management tools (Ansible, Terraform) that integrate with VMware for provisioning and lifecycle management.

Comparison (quick overview):

Use case	vmrun	PowerCLI / SDK
Quick CLI scripts	Good	Possible but heavier
Guest-level operations (run program, copy file)	Supported (requires VMware Tools)	Supported
Large-scale vSphere automation	Limited	Stronger integration
Cross-platform simple automation	Good (Workstation/Fusion)	PowerCLI is Windows-first but cross-platform via PowerShell Core

---

Summary

vmrun is a straightforward, script-friendly tool for controlling VMware virtual machines from the command line. It’s especially useful for starting/stopping VMs, snapshot management, and executing commands inside guests when VMware Tools are installed. For day‑to‑day automation and small orchestration tasks with VMware Workstation or Fusion, vmrun is fast and effective; for enterprise-scale vSphere automation, pair it with PowerCLI or vSphere APIs.

If you want, I can:

• Create ready-to-run scripts for your environment (Windows, macOS, or Linux).
• Convert examples to PowerCLI or Ansible playbooks.
• Help diagnose a vmrun error you’re seeing.