PowerShell’s Get-Childitem (gci)

Scripting Files with PowerShell’s Get-Childitem (gci)

Sooner or later you need a script which lists the files in a folder.  In DOS we would type: ‘DIR’; the nearest equivalent in PowerShell is gci.  The full name behind the gci alias is Get-ChildItem.  You can take the comparison further, dir /s in DOS, translates to Get-ChildItem -Recurse in PowerShell.

PowerShell Get-ChildItem Topics


Example 1: To List Files in the Root of the C:\ drive

Here is an example to get started, it will list all the files in the C:\ root.  If you need any help in executing the code, then see here.

# PowerShell script to list the files in C: root
Get-Childitem "C:\"

Note 1: In this instance C:\ is the root, and Get-Childitem lists any files at this location.

Note 2: Get-Childitem "C:\"  works equally well without the speech marks.  E.g.:
           Get-Childitem C:\   However, you do need the backslash after the colon, and you would need speech marks if the directory contained spaces.

Example 2: The Famous GCI -Recurse Parameter

Outside of PowerShell, recurse is a little known verb which means: rerun.  Inside of PowerShell, Get-ChildItem -Recurse is one of the most famous parameters meaning: repeat the procedure on sub-folders.

The point of example 2b is to list all the dll’s under the Windows folder.  Moreover, it will display their CreationTime, which helps determine if a file is up-to-date.  This technique is particularly useful for troubleshooting .dll files.

Example 2a: The Problem

Our goal is to find all the dlls under the Windows folder.  The problem is that this script does not search the system32 subdirectory.

# PowerShell gci example to list .dll in Windows folder
$Files = gci "C:\Windows\" | Where {$_.extension -eq ".dll"}
$Files | Format-Table Name, CreationTime, Length -auto

Note 3: I substituted the alias gci for Get-ChildItem

Note 4: This script lists only 4 dlls; surely there must be more?

Example 2b: The Solution

To find .dlls in the subdirectories let us append the Get-ChildItem -Recurse parameter.

# PowerShell example to list .dll in Windows folder and sub-folders
Write-Host `n "Waiting …."
$Files = gci "C:\Windows\" -Recurse | Where {$_.extension -eq ".dll"}
$Files | Format-Table Name, CreationTime, Length -auto

Note 5: I changed Name to FullName so that it would display the subdirectory where you can find the file.  See more on $_.extension.

Note 6: You could silence the error messages by introducing this after -Recurse:
 -ErrorAction SilentlyContinue

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

Example 2c: Extra Formatting

This example produces the same result but uses the -f formatting command and the alias Gci.

# PowerShell script to list the dll files under C:\Windows\System32
$i =0
$Files = Gci "C:\Windows\" –Recurse -EA 4 | ? {$_.extension -eq ".dll"}
Foreach ($Dll in $Files) {
"{0,-28} {1,-20} {2,12}" -f `
$Dll.name, $DLL.CreationTime, $Dll.Length
Write-Host `n The total number of dlls is: $i

Note 7: This example also uses three aliases; my principle reason was to make line 3 shorter.  Gci is an alias for our featured command Get-Childitem, while the question mark (?) is an alias for ‘where’. "-EA 4" means error action silently continue.

Note 8: The -Recurse parameter comes directly after the name of the directory.  For completeness, the location should be introduced by the -path parameter, but as this is optional, I have omitted the -Path parameter in this script.  However, this is how to include the -Path parameter.
$Files = gci -Path "C:\Windows\System32" -Recurse.

Trusty Twosome (Get-Help and Get-Member)

When you discover a new PowerShell command, it benefits from being probed with what I call the ‘Trusty Twosome’.  Experiment with Get-Help and Get-Member and unlock new scripting possibilities for Get-Childitem. To see what I mean try these two commands:

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

# (Try help gci) If you prefer abbreviations.
# (And help gci -full) If you like examples.

Note 9: Get-Help unearths useful parameters such as -Recurse, -exclude, it also reveals hidden files with: -Force.

# Research PowerShell Get-Childitem Properties
Get-Help Get-Childitem

Get-Childitem | Get-Member
# (gci | gm) If you enjoy aliases.
# (gci | gm -Membertype property) If want only properties

Note: Get-Member reveals properties that you don’t normally see in explorer, for example, CreationTime.

Engineer's Toolset v10Guy Recommends: SolarWinds Engineer’s Toolset v10

This Engineer’s Toolset v10 provides a comprehensive console of 50 utilities for troubleshooting computer problems.  Guy says it helps me monitor what’s occurring on the network, and each tool teaches me more about how the underlying system operates.

There are so many good gadgets; it’s like having free rein of a sweetshop.  Thankfully the utilities are displayed logically: monitoring, network discovery, diagnostic, and Cisco tools.  Try the SolarWinds Engineer’s Toolset now!

Download your fully functional trial copy of the Engineer’s Toolset v10

Example 3: List ALL Files, Including Hidden and System

# List ALL files in the root
$GciFiles = Get-Childitem C:\ -Force
$GciFiles | Sort-Object | FT Name, Attributes -auto
Write-Host "Number of files in the root: " $GciFiles.Count

Note 10: The key addition is the parameter -Force.  What this does is include hidden and system files.

Note 11: The additional commands enable us to count the files, this makes easier to see prove that -Force really makes a difference.  Double check what I mean by running the script with, and then without, the -Force switch.

See basic PowerShell examples featuring Get-ChildItem »

Example 4: Filter to List Just the System files

# PowerShell cmdlet to list JUST the System files in the root of C:\
$GciFiles = Get-ChildItem "C:\" -Force |where {$_.attributes -Match "System"}
$GciFiles | Sort-Object | Format-Table name, attributes -auto
Write-Host "Number of system files: " $GciFiles.Count

Note 12:  We need to employ the comparison parameter -Match "System", rather than -eq "System", this is because System files also have Hidden and other attributes.  Consequently, their attribute does not equal ”System”, although it does contain, or match the word System.

Note 13:  These last two examples employ the .count property rather than using the $i counter of previous scripts.  See more on GCI -Exclude and Where-Object.

Challenge 1:  Repeat the command with and without -Force.

Challenge 2:  Substitute this new ‘where’ clause on line 3: where {$_.attributes -ne "Directory"}. -ne is the opposite of -eq.  Thus this command filters out the directory entry.

# PowerShell cmdlet to list the System files in the root of C:\
$GciFiles = gci C:\ -Force |where {$_.attributes -ne "Directory"}
$GciFiles | Sort-Object | FT Name, Attributes -auto
Write-Host "Number of plain files: " $GciFiles.Count


# PowerShell script to investigate file properties
Get-ChildItem | Get-Member -Membertype property

Get-Childitem -Recurse can be surprisingly tricky, if this construction is giving you problems, see here for more help on -Recurse

Get-ChildItem Alias ‘Gci’

With Microsoft, there are always at least three ways of doing everything, what seems like redundancy when you are an expert, seems like perspective when you are a beginner.  Get-ChildItem has not one, but three aliases check thus:

# PowerShell Alias GCI
Get-Alias -Definition Get-ChildItem

Result: dir, ls and gci.

Parameter Aliases for Get-ChildItem
Starting in PowerShell 3.0 you can also use these aliases for PARAMTERS

Get-ChildItem C:\
-d, or -ad (Directory)
-af (File)
-h, -ah (Hidden)
-ar (ReadOnly)
-as (System)

Example 1: Get-ChildItem C:\ -as -force
Example 2: gci D:\ -ad

The Rest of the Item Family

# PowerShell Item Cmdlet Research
Get-Command -Noun Item

As expected there is an Get-Item cmdlet, but you may not realize there is a Move-Item cmdlet.  PowerShell -Noun or -verb research always throws up at least one surprise.

Get-Item (gi)
Also, a special mention of Test-Path
And my function Get-File

See more Get-ChildItem examples »

Summary of Get-ChildItem

Get-ChildItem, or its alias gci is an interesting and important PowerShell cmdlet.  Interesting because it has classic parameters such as -Force and -Recurse; important because it's the basis of so many scripts that need to interrogate not only the filesystem but also the registry or certificate store.

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


See more Microsoft PowerShell file tutorials:

PowerShell Home   • Add-Content   • Get-Content   • Set-Content  • PowerShell -Filter   • Test-Path

PowerShell Get-ChildItem   • Get-ChildItem -Include   • Get-ChildItem -Exclude   • Compare-Object

PowerShell Registry  • Get-Credential  • PowerShell ItemProperty  • PowerShell ItemPropery GCI

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.