PowerShell Get-Childitem -Filter

PowerShell GCI -Filter Parameter

Filter is the most useful parameter to refine the output of PowerShell cmdlets such as Get-ChildItem (gci).  I much prefer -Filter to -Include or -Exclude.

Topics for Get-ChildItem -Filter


Example 1: List only .dll Files with GCI -Filter

Let us assume we want a list of the dynamic link library (.dll) files.

$Files = "$Env:windir\System32"
Get-ChildItem $Files -Filter *.dll

Note 1: $Env:windir is a built-in variable that usually corresponds to:
C: \Windows.

Note 2: You could research more parameters with Get-Help gci.  For example, you could append -Force to search hidden directories, and -ErrorAction to suppress messages.

Example 2: Compare -Filter with -Include

I would always choose -Filter rather than -Include.  Filtering is faster, and the results are more predictable.

Let us try a head-to-head speed test between -Filter and -Include.  Here are the tasks for the comparison:

  1. Retrieve the .dll files with Get-ChildItem.
  2. Time the script in TotalMilliseconds with Measure-Command
  3. Check it retrieves the same number of files as Trial B.

Trial A -Filter Speed

# PowerShell GCI -Filter speed experiment
[Decimal]$Timing = (Measure-Command{
$Files = "$env:windir\System32"
$Result = Get-ChildItem $Files -Filter *.dll -Recurse -EA SilentlyContinue
$Timing =[math]::round($Timing)
Write-Host "TotalMilliseconds" $Timing
Write-Host "File count:" $Result.count


TotalMilliseconds 724
File count: 3685

Note 3: EA means ErrorAction.  You could also add the -Force parameter to both trials.

Note 4: I could not find any benefit from adding a ‘\’ or * to the path:
$Files = "$env:windir\System32\" made no difference, and \* was slower.

Trial B -Include Speed

# PowerShell GCI -Include speed experiment
$Timing = (Measure-Command{
$Files = "$env:windir\System32"
$Result = Get-ChildItem $Files -Include *.dll -Recurse -EA SilentlyContinue
$Timing =[math]::round($Timing)
Write-Host "TotalMilliseconds" $Timing
Write-Host "File count:" $Result.count


TotalMilliseconds 5884
File count: 3685

Note 5: It ‘feels’ longer when you run the -Include version; a fact confirmed by TotalMilliseconds.

Note 6: I employed [math]::round just to make it easier to read.

See more on PowerShell’s Measure-Command

Guy Recommends:  A Free Trial of the Network Performance Monitor (NPM)Review of Orion NPM v11.5 v11.5

SolarWinds’ Network Performance Monitor will help you discover what’s happening on your network.  This utility will also guide you through troubleshooting; the dashboard will indicate whether the root cause is a broken link, faulty equipment or resource overload.

What I like best is the way NPM suggests solutions to network problems.  Its also has the ability to monitor the health of individual VMware virtual machines.  If you are interested in troubleshooting, and creating network maps, then I recommend that you try NPM now.

Download a free trial of Solarwinds’ Network Performance Monitor

Research PowerShell Commands which Use the -Filter Parameter

Here is script to list cmdlets beginning with ‘Get’ which contain the -Filter parameter; feel free to modify for your own research.

# PowerShell script to research parameters
Get-Command | Where { $_.parameters.keys -Contains "Filter" -And $_.Verb -Match "Get"}

Note 7: The big benefit of PowerShell’s -Filter parameter is that the provider sifts the object as it retrieves them, which is much faster than obtaining the whole list, and only then including some items or excluding others.

Here is function I created to extend what Get-ChildItem can achieve.  Get-File function.

One Disadvantage of -Filter

You can only sift using one value with -Filter, whereas  -Include can accept multiple values, for example ".dll, *.exe"

Try Other Parameters

# Research PowerShell Get-Childitem Parameters
Get-Help Get-Childitem -Full

Note 8: This reveals parameters such as -Include and -Exclude.

Compare with PowerShell’s -Include parameter »

Summary of Get-ChildItem -Filter

PowerShell’s filter parameter is easy to use; it is also much faster than alternatives such as GCI -Include or -Exclude.

If you like this page then please share it with your friends


See more Microsoft PowerShell file tutorials:

PowerShell Home    • PowerShell Backup Copy-Item   • PowerShell Files  • Free Import CSVDE Tool

PowerShell Registry  • Get-Credential  • PowerShell ItemProperty   • PowerShell -Recurse

PowerShell Get-ChildItem  • PowerShell -Filter   • Free Permissions AnalyzerCompare-Object

Please email me if you have a better example script. Also please report any factual mistakes, grammatical errors or broken links, I will be happy to correct the fault.