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.
ScenarioCLI patching fitOperational noteStandalone ESXi host with no vCenterStrong fitOften the cleanest supported path when lifecycle tooling is not present.Isolated site or disconnected environmentGood fitUse an offline bundle and document the source, checksum, and profile.vLCM or SDDC Manager workflow blocked by a known issueConditional fitUse only when the KB or support case explicitly supports the workaround.Routine VCF workload domain patchingPoor fitPrefer SDDC Manager and vSphere Lifecycle Manager workflows.Cluster with unclear hardware/OEM image stateRiskyValidate OEM bundle requirements before applying a generic profile.No working backup, no rollback window, no console accessStopFix the maintenance plan first.
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:
ItemWhy it mattersHost FQDNTies the patch record to the asset.Current ESXi version and buildConfirms starting state.Current image profileHelps detect drift or mismatched remediation history.Current acceptance levelHelps identify unsigned or nonstandard packages.Installed OEM/vendor VIBsPrevents accidental removal or replacement.vCenter or SDDC Manager domainIdentifies lifecycle ownership.Offline bundle filenameSupports auditability.Target profile nameConfirms the selected remediation target.
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-<host>.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/<datastore-name>/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/<datastore-name>/patches/<bundle-name>.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:
Profile typeTypical meaningstandardSecurity and bugfix image including VMware Tools image updates.no-toolsSecurity and bugfix image without VMware Tools image updates.security-only style profileSecurity-only image, depending on bundle naming and release notes.OEM/vendor profileHardware-vendor-customized image profile, if supplied by the vendor.
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/<datastore-name>/patches/<bundle-name>.zip
-p <profile-name>
–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/<datastore-name>/patches/<bundle-name>.zip
-p <profile-name>
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:
Drift itemCaptureWhy CLI patching was usedChange ticket, support case, KB reference, or operational constraint.Normal lifecycle tool bypassedSDDC Manager, vLCM, standalone host, or direct ESXi.Target host and domainHost FQDN, cluster, workload domain, vCenter.Starting version/build/profilePre-change command output.Target bundle and profileBundle filename and selected image profile.Dry-run outputSaved terminal output or transcript.Final version/build/profilePost-change command output.Inventory sync actionAutomatic wait, API sync, or support case reference.Follow-up remediationRe-run prechecks, vLCM compliance, SDDC Manager inventory check.
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/<datastore-name>/patches/<bundle-name>.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
TaskCommandCheck ESXi versionvmware -vCheck ESXi version and release detailvmware -vlCheck system versionesxcli system version getCheck current image profileesxcli software profile getBack up config syncvim-cmd hostsvc/firmware/sync_configGenerate config backupvim-cmd hostsvc/firmware/backup_configEnter maintenance modevim-cmd /hostsvc/maintenance_mode_enterConfirm maintenance modevim-cmd /hostsvc/hostsummary | grep inMaintenanceModeList profiles in bundleesxcli software sources profile list -d <bundle.zip>Dry run profile updateesxcli software profile update -d <bundle.zip> -p <profile> –dry-runApply profile updateesxcli software profile update -d <bundle.zip> -p <profile>Reboot after patchingesxcli system shutdown reboot -r ‘apply patch’Exit maintenance modevim-cmd hostsvc/maintenance_mode_exit
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:
Confirm the host state.
Back up the host configuration.
Stage the correct offline bundle.
Enter maintenance mode cleanly.
List and choose the correct image profile.
Run a dry run.
Apply the profile update.
Reboot and validate.
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
Broadcom KB 343840: Patching ESXi host using Command Line
Broadcom KB 390985: Upgrading, updating, or applying a patch to ESXi host using esxcli command
Broadcom KB 313510: How to back up and restore the ESXi host configuration
Broadcom KB 390727: SDDC Manager Precheck Out-Of-Band Upgrade Error
Broadcom KB 324050: Synchronize inventory versions after out-of-band upgrade in a VMware Cloud Foundation Environment
Broadcom KB 316595: Build numbers and versions of VMware ESXi/ESX
Broadcom KB 345263: Determining the build number of VMware ESXi
Broadcom KB 311213: Using ESXi Shell in ESXi
Broadcom KB 406874: ESXUpdate image profile mismatch error reference
Broadcom KB 372545: Download ESXi patch and ISO guidance
ESXi PSOD Triage: Turning a Purple Screen into an Evidence-Driven Escalation
A purple screen on an ESXi host creates an immediate operational problem, but the bigger risk is what happens next. The first…
The post Command-Line ESXi Patching: A Controlled Workflow for Hosts Outside the Happy Path appeared first on Digital Thought Disruption.