Find unused portgroups in a cluster

Triggered by a recent post, see get-virtualportgroup, in the PowerCLI Community, I had a closer look at the Get-VirtualPortgroup cmdlet.

This cmdlet returns a VMware.VimAutomation.Types.Host.VirtualPortGroup object, which contains a very useful property called Ports. In that property it lists all the guests that are connected to a port on the portgroup. That would be the solution to find unused portgroups, I thought. But while the vSphere Client also shows powered off guests that are connected, the Port property returned by the Get-VirtualPortgroup cmdlet doesn’t. 🙁

So the question at hand required a bit more scripting than I originally thought.

The algortihm

The HostNetworkInfo object contains all the required information about vSwitches and portgroups.

To make it easier to link all the vSwitches, portgroups and used ports together I decided to go for PowerShell’s hash tables. This is a schematic view of the nested hash tables used in the script.

The script loops over all the ESX/ESXi hosts that belong to the cluster.

It populates the hash tables with the vSwitches, portgroups and ports it can find in the HostNetworkInfo object.

It loops through all the powered off guests on the hosts and find for each network card to which portgroup it is connected.

Finally the scripts displays the data it has captured in the hash tables on screen.

The script


Line 1: Specify the name of the cluster you want check for unused portgroups in variable $clusterName

Line 4: Loop over all the nodes for the requested cluster.

Line 8-17: Loop through all the vSwitches on the host and populate the $vsH hash table

Line 12-14: If there is a portgroup defined on this vSwitch that is not yet in the $pgH hash table, add it.

Line 19-36: Loop through all the portgroups on the host and add the data to the hash tables

Line 22-23: The $pgH hash table contains an array with hostnames of all the nodes where the portgroup is found.

Line 26-28: Inject the information from the Port property into the $puH hash table.

Line 39-53: Enter the information from the network cards for all powered off guests into the hash tables.

Line 46: Increment the counter of the used ports for a powered off guest.

Line 56-77: Display the results on screen.

Sample output

The following screenshot is from a run of the script on a 2-node cluster.

The report shows clearly that there is a portgroup, called PG77, on node esx4.test.local which has 0 ports in use.

This looks clearly like an unused portgroup and would require further investigation !


    Khoa Trinh

    Dear LucD,

    This script is great. However, i wonder did you or vmware public some document how we can manipulate and getting familiar with the powercli.

    I already wen to the link, but i don’ know how we can manipulate the object or try to discover the value properties.

    May you please give me a hint here ? . Thanks.


      Hi Khoa,
      For learning PowerCLI, and don’t forget you will need to have some basic PowerShell knowledge as well, there are a number of introductory resources available.
      See the sidebar on the PowerCLI blog for some pointers.
      For diving into the vSphere API you will need to refer to the API Reference, it also has sample code.

      On the PowerShell part, there is a good intro at the Microsoft MVA site.

      I hope that helps to get you started.


    Hi Luc,
    Wondering if there had been updates to this script to work with VDS and vSphere 5.5? This is exactly what I’m looking for in order to complete some tasks. Would appreciate any insight!


    I’m going to hazard a guess that you never determined why it didn’t work for vSphere 5.0+? Running into the same issue.


    This script does not seem to function properly on ESX 5.0. Are there changes that need to be made for the newer ESX versions? It’s not accurately displaying the VMs connected to my portgroups so most of them appear unused.



    I know this an old post, but what about Distributed Switches? They don’t seem to have to Ports property…


      Hi Jordan, yes, you are correct, that Ports property doesn’t exist for portgroups on dvSwitches.
      It should be possible to do this though, have a look at my dvSwitch scripting – Part 12 – Find free ports post, where I find the first free ports on a dvSwitch portgroup.
      I’ll see if I can come up with something.


    Hello Luc,

    You may find time to work on the script?

    best regards, Sven


      @Sven. I’m currently in the final days of writing for our upcoming book.
      Once that is done I will tackle all the open questions and requests.
      Sorry to keep you waiting.

    Yev Berman

    Fine, I’ll wait for it.

    Yev Berman

    Hey Luc,
    I haven’t seen any script that can generate a list of VLANs on dvSwitch,
    have you know some script that can do such a thing?
    Best regards,
    Yev Berman.


      There is indeed no such function (yet).
      I’ll have a look when I’m back home from VMworld


    Hello Luc,

    is there a way to modify the script to actually show

    – used ports or how much ports left (default switch 24 or 56) per host or cluster
    (for example i opened a case last week regarding disconnected machines after updating our esx hosts to U2. Reason/Problem: all ports were in use and therefor a few guests got disconnected from network/vSwitch)

    Thanks Luc


      That should be possible. But first I’m going to try to fix the problem with zero counters that was reported earlier.


    Would be nice if this can work with Virtulization EcoShell 🙂

    Output displays as part of the message window and not on the result windows


    After changing the cluster name on top of the script i run the script. It show’s me on several networks “Ports: 0” but there are 6 VM’s connected.
    The values for “used on: “ are correct.
    Best regards, Sven


    Very useful script. Thanks Luc.

Leave a Reply

Your email address will not be published.


This site uses Akismet to reduce spam. Learn how your comment data is processed.