Command-Line ESXi Patching: A Controlled Workflow for Hosts Outside the Happy Path

There are times when the normal ESXi patching path is exactly what you should use: SDDC Manager, vSphere Lifecycle Manager, a tested cluster image, prechecks, staged remediation, and a maintenance workflow that keeps inventory and compliance aligned.

Then there are the other days.

A host might be standalone. A lab host might not be attached to vCenter. A break-fix situation might require a surgical patch outside the normal lifecycle workflow. A vendor or Broadcom support case might point you to a command-line path because the standard remediation workflow is blocked. That is where KB 343840 becomes useful, but it should not be treated as a casual shortcut.

The goal is not “patch ESXi from SSH because it is faster.” The goal is to run a controlled, evidence-backed workflow when the host is outside the happy path.

Broadcom’s KB343840 describes command-line ESXi patching with esxcli software profile, and it specifically calls out that profile update is the recommended method for applying patches because it applies newer patch content while ignoring lower-revision content already on the host. The same KB warns that profile install can overwrite or downgrade packages and should be used carefully.

This walkthrough focuses on the operational version of that process: when to use it, what to capture before you touch the host, how to choose the right image profile, how to validate the result, and how to document drift afterward.

What You Will Accomplish

By the end of this walkthrough, you will have a repeatable command-line workflow for patching an ESXi host using an offline bundle.

The workflow covers:

• when CLI patching is appropriate
• maintenance mode and workload evacuation
• host configuration backup
• offline bundle staging
• image profile selection
• dry-run validation
• patch execution
• reboot planning
• post-patch verification
• drift documentation for vCenter, SDDC Manager, or operational records

This is written for administrators and engineers who already understand ESXi operations but want a safer command-line pattern than copying a single esxcli command from a KB and hoping the environment cooperates.

Where CLI Patching Fits

Command-line patching is an exception path. It has value, but the context matters.

The reason this distinction matters is simple: in VCF-managed environments, out-of-band ESXi updates can create lifecycle drift. Broadcom documents a case where SDDC Manager precheck fails because ESXi hosts were upgraded manually outside SDDC Manager workflows, causing a version mismatch between the actual host deployment and the SDDC Manager inventory database.

That does not mean you can never patch from the CLI in a VCF-adjacent environment. It means you need to treat the CLI patch as a controlled exception and record what changed.

The Workflow at a Glance

The most important part of this process is sequencing. Do not start with the profile update command. Start with evidence, readiness, and rollback.

Notice what the diagram does not show: “SSH to the host and immediately run the patch.” The safe workflow is slower up front and faster when something goes wrong.

Prerequisites and Assumptions

This walkthrough assumes:

• You have administrative access to the ESXi host.
• You have a maintenance window approved for workload evacuation and reboot.
• You have console access or out-of-band management available.
• You have downloaded the correct ESXi offline bundle.
• You know whether the host requires an OEM-customized image.
• You understand whether the host is standalone, vCenter-managed, or VCF-managed.
• You have enough datastore space to stage the bundle.
• You have a rollback or reinstall path if the host does not return cleanly.

Broadcom’s ESXi Shell guidance describes ESXi Shell as primarily intended for break-fix scenarios and exceptional cases that cannot be handled through standard management or CLI tools. That framing is useful. Enabling SSH or ESXi Shell for patching should be temporary, intentional, and logged.

Step 1: Confirm the Current Host State

Before staging a patch, capture the current version, build, image profile, and maintenance context.

From the ESXi shell:

vmware -v
vmware -vl

esxcli system version get
esxcli software profile get
esxcli software vib list | sort

Broadcom documents vmware -v as a CLI method to determine the ESXi build number. The image profile matters because a host can show one ESXi version while its underlying image profile is not aligned. Broadcom has documented cases where image profile mismatch can break later VIB-related operations, and the ideal state is for the ESXi version and image profile details to align.

Capture the output into your change record. At minimum, record:

For current build mapping, Broadcom maintains an ESXi build-number table that lists ESXi and ESX builds by release date.

Step 2: Back Up the Host Configuration

Do not skip the host configuration backup.

From the ESXi shell:

vim-cmd hostsvc/firmware/sync_config
vim-cmd hostsvc/firmware/backup_config

The first command synchronizes configuration changes to persistent storage. The second command generates a URL for downloading the configuration bundle. Broadcom documents both commands in the ESXi host configuration backup workflow.

Download the generated configBundle-.tgz and store it with the change record.

A host configuration backup is not the same thing as a full bare-metal image. It is still valuable because it gives you a recovery path after reinstalling the same ESXi build, assuming the restore conditions are met. Broadcom notes that restore requires the destination host build number to match the build from which the backup was taken and that the UUID remains the same.

If you prefer to collect this evidence from PowerCLI before entering the break-fix window, you can use a small evidence script.

# Connect to vCenter or directly to the ESXi host, depending on your environment.
# Update these values before running.
$ServerName = "vcsa01.lab.local"
$HostName   = "esx01.lab.local"
$EvidenceRoot = ".\esxi-patch-evidence"
$Stamp = Get-Date -Format "yyyyMMdd-HHmmss"
$EvidencePath = Join-Path $EvidenceRoot "$HostName-$Stamp"

New-Item -ItemType Directory -Path $EvidencePath -Force | Out-Null

Connect-VIServer -Server $ServerName

$VMHost = Get-VMHost -Name $HostName

# Capture the inventory view from vCenter.
$VMHost |
    Select-Object Name, Version, Build, ConnectionState, PowerState, Parent |
    Export-Csv -Path (Join-Path $EvidencePath "vmhost-inventory-before.csv") -NoTypeInformation

# Capture host services visible through PowerCLI.
Get-VMHostService -VMHost $VMHost |
    Select-Object VMHost, Key, Label, Running, Policy |
    Export-Csv -Path (Join-Path $EvidencePath "vmhost-services-before.csv") -NoTypeInformation

# Optional: capture a host configuration backup when network and policy allow it.
Get-VMHostFirmware -VMHost $VMHost -BackupConfiguration -DestinationPath $EvidencePath

Disconnect-VIServer -Server $ServerName -Confirm:$false

What to change:

• $ServerName should be your vCenter Server or target ESXi host.
• $HostName should be the ESXi host being patched.
• $EvidenceRoot should point to your change record or operations share.

Broadcom documents PowerCLI-based ESXi configuration backup using Get-VMHostFirmware -BackupConfiguration, with the note that HTTP 80 and HTTPS 443 are required for the cmdlet to work.

Step 3: Download and Stage the Offline Bundle

Use the offline bundle ZIP, not the ISO, for the esxcli software profile update workflow.

Broadcom’s download guidance states that only product versions with active licensing appear in the Broadcom Support Portal, and it separates ISO releases under Products from patch releases under Solutions. For ISO releases, Broadcom also notes that the desired download type can include an ISO or offline bundle ZIP.

Stage the bundle on a datastore accessible by the target host. A clean pattern is to create a dedicated directory:

mkdir /vmfs/volumes//patches

Then upload the ZIP through the datastore browser, SCP, or another approved file-transfer method.

Example staged path:

/vmfs/volumes/datastore1/patches/VMware-ESXi-8.0U3x-########-depot.zip

Use your actual bundle filename. Do not rename it in a way that hides the version or build.

Step 4: Put the Host in Maintenance Mode

Before patching, migrate or power off running virtual machines, then place the host into maintenance mode.

vim-cmd /hostsvc/maintenance_mode_enter
vim-cmd /hostsvc/hostsummary | grep inMaintenanceMode

Broadcom’s KB 343840 includes the maintenance mode entry command and the hostsummary validation command as part of the command-line patch workflow.

If the host is part of a DRS-enabled cluster, vCenter can migrate workloads after maintenance mode is initiated. Broadcom also notes that when vCLS is running on the target host, vCenter will automatically migrate off or shut down the vCLS VM and that you should not manually migrate or power off vCLS VMs unless instructed by Broadcom VCF Global Support.

For vSAN clusters, treat this as a storage-impacting operation, not just a compute evacuation. Confirm the evacuation mode, object health, and policy impact before continuing.

Step 5: List the Image Profiles in the Offline Bundle

Now inspect the bundle before applying anything.

esxcli software sources profile list -d /vmfs/volumes//patches/.zip

Example:

esxcli software sources profile list -d /vmfs/volumes/datastore1/patches/VMware-ESXi-8.0U3x-########-depot.zip

Broadcom’s command-line patch KB uses this exact pattern to list profile names from the offline bundle.

This is where image profile awareness matters. You may see profiles such as:

Broadcom’s KB 390985 documents common VMware original offline bundle profile patterns, including standard, no-tools, and security-only profile examples. It also states that when a hardware vendor provides custom offline bundles for specific hardware, you should use the vendor bundle instead of the VMware original offline bundle.

This is one of the most common places where operators create long-term drift. If the host was installed from a Dell, HPE, Lenovo, Cisco, or other OEM-customized image, verify whether the target patch should also come from the OEM channel.

Step 6: Run a Dry Run

Do not apply the patch first. Simulate the transaction.

esxcli software profile update \
  -d /vmfs/volumes//patches/.zip \
  -p  \
  --dry-run

Example:

esxcli software profile update \
  -d /vmfs/volumes/datastore1/patches/VMware-ESXi-8.0U3x-########-depot.zip \
  -p ESXi-8.0U3x-########-standard \
  --dry-run

KB 343840 documents --dry-run as an option that simulates the installation and reports actions without making changes.

Review the output for:

• VIBs to be installed
• VIBs to be removed
• dependency errors
• acceptance-level warnings
• hardware compatibility warnings
• signature warnings
• reboot requirement
• OEM or custom package removal

Do not treat --force, --no-sig-check, or hardware-warning bypass options as normal operational switches. KB 343840 states that --force bypasses dependency and security checks and is not recommended unless instructed by VMware Support. It also states that --no-sig-check disables security verification and poses a high security risk.

Step 7: Apply the Profile Update

If the dry run is clean and the maintenance window is active, apply the update.

esxcli software profile update \
  -d /vmfs/volumes//patches/.zip \
  -p 

Example:

esxcli software profile update \
  -d /vmfs/volumes/datastore1/patches/VMware-ESXi-8.0U3x-########-depot.zip \
  -p ESXi-8.0U3x-########-standard

Use profile update as the default. Use profile install only when you explicitly intend to replace the image profile and understand the package-removal and downgrade implications. Broadcom’s KB 343840 makes the distinction clear: update is recommended for applying patches, while install can overwrite existing packages, remove old packages, or downgrade packages.

Also avoid using esxcli software vib update or esxcli software vib install for ESXi 8.0 Update 2 and later update/upgrade workflows. Broadcom states that starting with ESXi 8.0 Update 2, upgrading or updating ESXi using those VIB commands is no longer supported.

Step 8: Reboot the Host

After the patch transaction completes successfully, reboot the host.

esxcli system shutdown reboot -r 'apply patch'

Broadcom’s KB 343840 includes this reboot step after patch installation. KB 390985 is even more explicit operationally: upgrading, updating, or applying a patch is not finished until the ESXi host completes the reboot after the update command.

Do not power off the server during this window. Watch the out-of-band console, iDRAC, iLO, IMM/XCC, UCS Manager, or your platform equivalent until the host has fully returned.

Step 9: Validate the Result

After the host boots, validate from both the host and the management plane.

From ESXi:

vmware -v
vmware -vl

esxcli system version get
esxcli software profile get
esxcli software vib list | sort

Confirm:

• ESXi version and build match the expected target.
• The image profile matches the selected target profile.
• The host services are running as expected.
• vmkernel adapters, storage adapters, and uplinks are present.
• datastores are visible.
• vSAN, NSX, or other platform-specific services are healthy where applicable.
• no unexpected OEM or custom VIBs were removed.

Then exit maintenance mode:

vim-cmd hostsvc/maintenance_mode_exit

KB 343840 includes exiting maintenance mode after the host finishes booting.

If the host is vCenter-managed, validate through vCenter as well:

$ServerName = "vcsa01.lab.local"
$HostName   = "esx01.lab.local"
$EvidencePath = ".\esxi-patch-evidence\$HostName-post"

New-Item -ItemType Directory -Path $EvidencePath -Force | Out-Null

Connect-VIServer -Server $ServerName

$VMHost = Get-VMHost -Name $HostName

$VMHost |
    Select-Object Name, Version, Build, ConnectionState, PowerState, Parent |
    Export-Csv -Path (Join-Path $EvidencePath "vmhost-inventory-after.csv") -NoTypeInformation

Get-VMHostService -VMHost $VMHost |
    Select-Object VMHost, Key, Label, Running, Policy |
    Export-Csv -Path (Join-Path $EvidencePath "vmhost-services-after.csv") -NoTypeInformation

Disconnect-VIServer -Server $ServerName -Confirm:$false

The output gives you a before-and-after record for the change ticket.

Step 10: Document Drift in VCF or Lifecycle-Managed Environments

This is the part that separates a controlled exception from a future outage.

If the host belongs to a VCF-managed domain, do not assume that a successful ESXi boot means lifecycle management is clean. SDDC Manager may still have inventory or version metadata that needs to catch up.

Broadcom documents a version synchronization API for VCF inventory after an out-of-band upgrade. The API can perform global or per-domain inventory version synchronization and can filter by product type, including ESXi. The same KB notes that inventory sync runs daily at 03:00 local server time, but it also provides an API workflow when manual synchronization is needed.

Your drift record should include:

Do not leave this as tribal knowledge. The next upgrade precheck will surface the gap, and the person troubleshooting it may not be the person who patched the host.

Troubleshooting and Common Issues

“No image profile found with name”

This usually means the profile name was typed incorrectly or copied from the wrong bundle.

Run the profile list command again:

esxcli software sources profile list -d /vmfs/volumes//patches/.zip

Copy the exact profile name.

“The host is not in maintenance mode”

Verify maintenance mode:

vim-cmd /hostsvc/hostsummary | grep inMaintenanceMode

If it returns false, evacuate or power off workloads and re-enter maintenance mode.

Hardware or dependency warnings

Stop and review. Do not blindly add bypass flags.

If the host uses an OEM image, confirm whether you are using the right vendor bundle. Broadcom notes that when hardware vendors provide custom offline bundles for specific hardware, you should use those instead of the VMware original offline bundle.

VIB command guidance conflicts with older notes

Older articles, scripts, or personal notes may still reference esxcli software vib update. For ESXi 8.0 Update 2 and later update/upgrade workflows, Broadcom states that VIB update/install commands are no longer supported for upgrading or updating ESXi. Use esxcli software profile update for the host image profile path.

SDDC Manager shows mixed host versions after manual patching

Treat this as lifecycle drift, not just a cosmetic warning. Broadcom documents that SDDC Manager can show mixed host versions when ESXi hosts were manually upgraded outside SDDC Manager workflows, causing mismatch between actual deployment and SDDC Manager inventory. Review the VCF inventory version synchronization guidance and rerun the relevant prechecks.

Rollback is needed

Your realistic rollback options depend on the host state, bootbank behavior, and whether the previous version can be reverted. Broadcom’s ESXi patching KB references rollback guidance and also notes that if rollback cannot be used, reinstalling the old ESXi version and restoring the configuration backup may still be an option.

This is why the configuration backup and pre-change evidence are not optional.

Command Reference

Wrap-Up

Command-line ESXi patching is useful when the host is outside the normal lifecycle path, but it should never feel informal.

The safe pattern is:

1. Confirm the host state.
2. Back up the host configuration.
3. Stage the correct offline bundle.
4. Enter maintenance mode cleanly.
5. List and choose the correct image profile.
6. Run a dry run.
7. Apply the profile update.
8. Reboot and validate.
9. Document drift and lifecycle ownership.

KB 343840 gives the core command-line mechanics. The operational value comes from wrapping those mechanics in a controlled workflow that respects image profiles, maintenance mode, offline bundle provenance, reboot planning, and VCF inventory state.

That is the difference between “I patched a host from SSH” and “I executed a controlled exception with evidence.”

External Sources