How to Change a vmnic Name on an ESXi Host via CLI (localcli alias store)

Rename or reorder vmnic aliases on ESXi with localcli deviceInternal alias list/store: update both PCI and logical aliases, then reboot.

Short answer: ESXi has no vSphere Client workflow for renaming a vmnic. The documented method is the internal localcli ... deviceInternal alias namespace: list the current aliases, store the new alias for the NIC’s PCI bus address and, for native drivers, also for its logical (uplink) address, then cleanly reboot. Work from the host console, because management networking can drop while uplinks are renumbered.

Why vmnic numbering gets out of order

ESXi assigns vmnicN aliases from information the firmware provides. According to Broadcom KB 324534, onboard ports are named first, then ports the firmware does not describe, then ports in pluggable slots ordered by slot number. After that the names are largely static: when cards are added or removed, remaining ports keep their names and a new port gets the first free alias. A host that had a NIC replaced, a card moved to another slot, or a firmware change can therefore end up with numbering that no longer matches the other hosts in the cluster.

That is more than cosmetic. Host profiles, scripted vSwitch builds, VCF network profiles and vDS uplink mappings usually assume that vmnic0 and vmnic1 are the same physical ports on every host. Broadcom KB 409368 states there is no workflow in the vSphere environment to change the alias directly, and points to the CLI procedure below.

Step 1: List the current vmnic aliases

Open the DCUI shell or an SSH session (keep console access available) and run:

localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias list

The output has three columns: bus type, bus address and alias. A shortened example based on the KB:

Bus type  Bus address          Alias
------------------------------------
pci       s00000002.00         vmnic0
pci       s00000002.01         vmnic1
pci       s00000008.03         vmnic7
logical   pci#s00000008.03#0   vmnic7

Cross-check which physical port is which with esxcli network nic list (PCI address, driver, MAC, link state) before changing anything.

Step 2: Understand PCI vs. logical aliases

A NIC controlled by a native driver has two aliases: a pci alias for the PCI function and a logical alias for the uplink object the driver creates. The logical bus address wraps the PCI address, for example pci#s00000008.03#0. If a logical alias exists for the device, rename both, otherwise the result is inconsistent.

Bus typeBus address formatWhen present
pcis00000008.03Always
logicalpci#s00000008.03#0NICs using native drivers

Step 3: Store the new vmnic name

To give the port at s00000008.03 the name vmnic0 (the KB’s own swap example), run both commands:

localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias store --bus-type pci --alias vmnic0 --bus-address s00000008.03
localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias store --bus-type logical --alias vmnic0 --bus-address "pci#s00000008.03#0"

If you are swapping two names, also store the old name on the other port in the same session so that no two devices end up claiming the same alias. Quote the logical address, because it contains # characters.

Step 4: Reboot and verify

  1. Put the host into maintenance mode.
  2. After all alias store commands, perform a clean shutdown and reboot. The new names only apply after the reboot.
  3. Run the alias list command and esxcli network nic list again and confirm the mapping.
  4. Check vSwitch and vDS uplink assignments and the management VMkernel port, then exit maintenance mode.

Things to watch

  • Console access first. The KB explicitly requires it. If the management uplink changes number, the host may come up unreachable over the network.
  • Host profiles. If the host is managed by a host profile, capture an updated profile after the change, as the KB recommends.
  • Hardware re-enumeration. If aliases keep moving after firmware or hardware changes, open a case with the server vendor; the root cause is the firmware data, not ESXi.
  • Upgrades. Upgrades normally preserve aliases, but verify the mapping after a major upgrade or a legacy BIOS to UEFI switch.

For other everyday host commands see my esxcli commands for ESXi 8.0 reference.

Further reading

Author: Daniel Micanek

Senior Service Architect, SAP/TDL Platform Services Team at Vivicta | vExpert ⭐⭐⭐⭐⭐⭐⭐ | Broadcom Knight: vSphere Kubernetes Service, VCF Networking (NSX), VCF Automation | Broadcom Software Knight: vSphere | Cisco Champion. Notes from running about 1,000 ESXi hosts on Cisco UCS, VCF 9 and SAP HANA on vSphere.