PowerShell Get-Childitem Explained: Syntax, Parameters, And Examples

Have you wondered what PowerShell Get-Childitem is about and how to use the Cmdlet? In this in-depth guide, I dive into this popular Cmdlet.

I kick the guide off with an overview of the Get-Childitem Cmdlet. Then, in the second section, you’ll learn the Syntax of the Cmdlet.

I also have a section that explains the parameters of the PowerShell Get-Childitem. Then, I have a section dedicated to examples and applications of the Get-Childitem Cmdlet.

If you still have questions after reading all these, I included an FAQ section with commonly asked questions about this popular Cmdlet.

PowerShell Get-Childitem: Overview

PowerShell Get-Childitem: Overview

The easiest way to explain Get-Childitem is that it is like the dir command in Command Prompt. Like the dir command, Get-Childitem lists the content of a directory or folder.

However, the PowerShell Get-Childitem returns more information and has more options than the dir command. On the flip side of the coin, the dir command is faster.

Anyway, the most important thing to note about the Get-Childitem Cmdlet is that it is used to list the content of a directory. But, as you’ll see in subsequent sections, it does much more than just list the content of a directory.

A better definition of the PowerShell Get-Childitem Cmdlet is that you can use it to list the items and child items in one or more specified locations. For clarity, a “location” could be a file system directory, registry hive, or a certificate store.

Like most PowerShell Cmdlets, Get-ChildItem has an alias. The alias of the Get-ChildItem is gci.

So, when you write scripts, you can use gci instead of using Get-ChildItem.

Syntax Of PowerShell Get-Childitem

Syntax Of PowerShell Get-Childitem

The Get-Childitem Cmdlet has two syntaxes.

Get-ChildItem
   [[-Path] <string[]>]
   [[-Filter] <string>]
   [-Include <string[]>]
   [-Exclude <string[]>]
   [-Recurse]
   [-Depth <uint32>]
   [-Force]
   [-Name]
   [-Attributes <FlagsExpression[FileAttributes]>]
   [-UseTransaction]
   [-Directory]
   [-File]
   [-Hidden]
   [-ReadOnly]
   [-System]
   [<CommonParameters>]*
Get-ChildItem
   [[-LiteralPath <string[]>
   [[-Filter] <string>]
   [-Include <string[]>]
   [-Exclude <string[]>]
   [-Recurse]
   [-Depth <uint32>]
   [-Force]
   [-Name]
   [-Attributes <FlagsExpression[FileAttributes]>]
   [-UseTransaction]
   [-Directory]
   [-File]
   [-Hidden]
   [-ReadOnly]
   [-System]
   [<CommonParameters>]*

*CommonParameters is a set of parameters that Windows PowerShell automatically adds to Cmdlets that support it. Since this set of parameters is common, I’ll not include this parameter in the next section

The difference between the two syntaxes is the Path and LiteralPath parameters. Every other parameter is the same in both syntaxes.

The implication is that when you run the PowerShell Get-ChilItem command, you CAN NOT use the Path and LiteralPath parameters in the same command. So, you can either use one or the other.

In the next section, I will explain the meaning of each parameter.

Parameters Of PowerShell Get-Childitem

Parameters Of PowerShell Get-Childitem

In the table below, I have listed all the parameters of the Get-Childitem Cmdlet. Also, I have explained what each parameter does.

S/N Get-Childitem Parameter Name Get-Childitem Parameter Meaning/Notes
1 Path Use the Path parameter to specify a path to one or more locations. Wildcards are accepted. The default location is the current directory (.).
2 LiteralPath This parameter is also used to specify a path to one or more locations. However, unlike the Path parameter, LiteralPath does not permit the use of wildcards – its value is used exactly as it’s typed.
3 Filter Using the filter parameter offers you a very efficient way to reduce the output of the Get-Childitem. You use this parameter to qualify the Path parameter.
4 Include Use this parameter to specify an array of string patterns to be matched as Get-Childitem gets child items in a specified location. The Include parameter supports wildcards.
5 Exclude Similar to the Include, but instead of including the matched pattern, when you use the Exclude parameter, the Get-Childitem Cmdlet will not include items that match a specified pattern
6 Recurse This is a Switch parameter, meaning that it does not require any input. When you specify the Recurse parameter, PowerShell Get-Childitem returns all items in the specified locations. In addition to that, the Cmdlet also returns all child items of the locations.
7 Depth The Depth parameter allows you to control the depth of recursion. In other words, the Depth parameter determines the number of subdirectory levels that are included in the recursion.
8 Force When you specify the Force parameter, the PowerShell Get-Childitem Cmdlet can return items that otherwise can’t be accessed by the user, such as hidden or system files. Note that the Force parameter does not override security rules.
9 Name Use the Name parameter to return the names of the items in a specified location.
10 Attributes This is a very important parameter. When you specify the Attributes parameter, you can return files and folders with the specified attributes.
11 UseTransaction Like the Recurse parameter, the UseTransaction parameter is a Switch parameter. This means that you do not need to specify a value when using the UseTransaction parameter. In terms of application, the UseTransaction parameter includes the command in the active transaction – only valid when a transaction is in progress.
12 Directory This is also a Switch parameter (no input required). If you specify the Directory parameter, Get-Childitem returns only a list of directories. Another way to return only directories is to use the Attributes parameter and specify Directory as the property
13 File To get a list of files in a specified path, use the File parameter. You can also use the Recurse parameter with the File parameter.
14 Hidden To get the Get-Childitem Cmdlet to return only hidden items, use the Hidden parameter. Alternatively, you can use the Attributes parameter and specify the Hidden property.
15 ReadOnly To get only read-only items (files, or folders), use the ReadOnly parameter. Another way to achieve the same result is to use the Attributes parameter and specify ReadOnly as the attribute you wish to return.
16 System If you want the Get-Childitem Cmdlet to get only system files and folders, use the System parameter. Alternatively, you can use the Attributes parameter with the System property.

PowerShell Get-Childitem Examples

PowerShell Get-Childitem Examples

In this section of the guide, you’ll learn different ways you can use the Get-Childitem command.

How To Use The “Path” And “Literalpath” Parameters In PowerShell Get-Childitem

In the last section of the guide, I explained the parameters of the Get-Childitem Cmdlet. In that section, two of the parameters – “Path” And “Literalpath” – stood out.

If you recollect, I said that you cannot use the two parameters in the same command. The reason is that the two parameters work differently.

Specically, when you use the Path Parameter, you can use wildcards. However, when you use the Literalpath Parameter, you have to use the full path – it does not support the use of wildcards.

In this example, I’ll show you how to use Path or Literalpath Parameter in PowerShell Get-Childitem.

In my first example, I want to return the files in the path “C:\WINDOWS\System32”. To do this by specifying the Path parameter I will run the command below.

Get-ChildItem -Path 'C:\WINDOWS\System32\*' -File

In the command above, I included asterisks (*) at the end of the last slash after “System32”. The asterisks (*) is a wildcard that tells Get-ChildItem to use return values from the System32 and all its subfolders.

When you run the last command, the result will scroll for a long time. To stop the command, press the Ctrl and the C keys together.

Here is the result of the command.

PowerShell Get-Childitem Examples - How To Use The "Path" And "Literalpath" Parameters In PowerShell Get-Childitem

On the other side of the coin, if I want to use the Literalpath Parameter, I’ll specify the path in full; without any wildcards. So, let me start by adding a wildcard at the end of the path…

Get-ChildItem -Literalpath 'C:\WINDOWS\System32\*' -File

The command will return an error message “Cannot find path ‘C:\WINDOWS\System32*’ because it does not exist.”

The reason for this error is that the Literalpath Parameter inteprets the specified path exactly as it’s typed.

So, to fix the problem, I’ll now run the command without the asterisks (*) at the end of the last slash after “System32”.

Get-ChildItem -Literalpath 'C:\WINDOWS\System32\' -File
PowerShell Get-Childitem Examples - How To Use The "Path" And "Literalpath" Parameters In PowerShell Get-Childitem

How To Use PowerShell Get-Childitem To Get Directory Or Folders Only

To return only directory or folders with the Get-Childitem command, use the Directory parameter. Here is a sample command.

Get-ChildItem -Path 'C:\WINDOWS\System32\' -Directory

Here is the result of the command in PowerShell…

Alternatively, if you do not want to use the Directory parameter, you can pipe the output of Get-Childitem to Where-Object. Then, filter PSIsContainer property.

Here is the command in PowerShell…

Get-ChildItem -Path 'C:\WINDOWS\System32\' | Where-Object {$_.PSIsContainer -eq $TRUE}

The command returns the same result as the previous command…

How To Use PowerShell Get-Childitem To Get Directory Or Folders Only

To help you understand the last command, here is a brief explanation.

Get-ChildItem -Path 'C:\WINDOWS\System32\' | Where-Object {$_.PSIsContainer -eq $TRUE}

When you run the PowerShell Get-Childitem command, the items returned has a property called PSIsContainer. Any object that has this property is a directory.

So, when you specify “Where-Object {$_.PSIsContainer -eq $TRUE}”, you’re asking PowerShell to return objects where the property PSIsContainer is true.

How To Use PowerShell Get-Childitem To Get Files But Exclude Directories

In the last example, I showed you two methods you can use to Directories only. However, sometimes you may want to exclude Directories and return only files.

You can complete this task in two ways. One, by specifying the File parameter.

Get-ChildItem -File -Path 'C:\WINDOWS\System32\*' 

Another way to achieve the same goal is to pipe the output of Get-ChildItem to Where-Object. Then, specify PSIsContainer property as False.

Get-ChildItem -Path 'C:\WINDOWS\System32\' | Where-Object {$_.PSIsContainer -eq $FALSE}
How To Use PowerShell Get-Childitem To Get Directory Or Folders Only

How To Exclude A Sub-folder In PowerShell Get-Childitem Command

In some instances, you may want to exclude a specific folder from the results of the Get-Childitem command.

To demonstrate this, I will exclude the folder “Get-FolderSizeFileCount” from the result of Get-Childitem command. See the screenshot below.

I can achieve this in two ways:

1, I can pipe the output of Get-ChildItem to Where-Object. Then, I will use the “Not Equal” operator to filter out the folder the folder.

Get-ChildItem -Path "D:\PowerShell Scripts" |  Where-Object {$_.Name -ne 'Get-FolderSizeFileCount'}

Alternatively, I can use the Exclude parameter of the Get-ChildItem to remove the folder I do not want PowerShell Get-Childitem to process.

Get-ChildItem -Path "D:\PowerShell Scripts" -Exclude Get-FolderSizeFileCount

Both commands produces the same result. See the screenshots below.

How To Exclude A Sub-folder In PowerShell Get-Childitem Command

How To Get The Full Path And The Name Of A Directory With PowerShell Get-Childitem

When you run the Get-Childitem command, it returns the properties of objects. Two of the properties that Get-Childitem returns are the Name and Full Path of the items.

So, it is easy to return the Name and Full Path of Directories when you run PowerShell Get-Childitem command.

To demonstrate, I’ll return the names and full path of all directories in the screenshot below.

Before, I run the command though, I need to determine the names of the two properties that represent the information I want to return.

To achieve this, I will pipe the output of the Get-ChildItem command to Get-Member.

Get-ChildItem -Path 'C:\WINDOWS\System32\' -Directory | Get-Member

As shown in the screenshot below, the command returns lots of properties. I have highlighted the two that I require for my command.

The Name property is easy to identify. However, the FullName property is not as straightforward.

I was able to identify this parameter as the Full Path of the directory because of my experience. However, if you’re new to PowerShell, you can start by highlighting all the properties you believe may represent what you need.

Then, try returning the properties to see what the result shows.

Moving on, based on the information I have from my previous command, I’ll use the command below to get the Full Path and Name of a Directory.

Get-ChildItem -Path 'C:\WINDOWS\System32\' -Directory | Select-Object Name, "FullName"

As you can see from the screenshot below, the command returns the full path, including the name of the folder (directory) itself.

How To Assign The Output Of PowerShell Get-Childitem To A Variable And Use In A Foreach Loop

To demonstrate this example, I’ll continue from the previous example. In the last example, I returned the Name, and “FullName” (Full Path) of a Directory.

To refresh your memory, here is the command I used in the last sub-section.

Get-ChildItem -Path 'C:\WINDOWS\System32\' -Directory | Select-Object Name, "FullName" 

Although the command returned the full path to the directory, it included the name of the directory to the path.

How To Assign The Output Of PowerShell Get-Childitem To A Variable And Use In A Foreach Loop

But, wait a minute, I do not want the path to include the name of the directory itself. One way to do this is to loop the output of the PowerShell Get-Childitem in a Foreach.

However, to reduce the complexity of the code, it is better to save the output of the Get-Childitem command in a variable.

To save the command below in a variable, modify the command as shown in the second command below the first one…

Get-ChildItem -Path 'C:\WINDOWS\System32\' -Directory | Select-Object Name, "FullName" 
$dirs = Get-ChildItem -Path 'C:\WINDOWS\System32\' -Directory | Select-Object Name, "FullName" 

In the second command, I simply added “$dirs =”. In the command, “$dirs” is the variable.

Next, I want to bring in PowerShell Foreach. I will then modify the last script as shown below:

$dirs = Get-ChildItem -Path 'D:\PowerShell Scripts\' -Directory | Select-Object Name, "FullName" 
  ForEach ($dir in $dirs) {
    $ParentPath = Split-Path -Parent $dir.fullname
    $FolderName = $dir.Name
#creatde an empty report container
    $Report = "" | Select-Object -Property "Folder Name", "Full Path"
#link the properties of the report to the outout of lines 3 and 4 
    $Report.'Folder Name' = $FolderName
    $Report.'Full Path' = $ParentPath
#finally, call the report
$Report
}

Here is the result of the script in PowerShell ISE. Beneath the screenshot below, I have a detailed explanation of the script.

To make it easier for you to follow my explanation of the script, I have added line numbers.

1 $dirs = Get-ChildItem -Path 'D:\PowerShell Scripts\' -Directory | Select-Object Name, "FullName" 
2  ForEach ($dir in $dirs) {
3  $ParentPath = Split-Path -Parent $dir.fullname
4  $FolderName = $dir.Name
5 #creatde an empty report container
6   $Report = "" | Select-Object -Property "Folder Name", "Full Path"
7 #link the properties of the report to the outout of lines 3 and 4 
8   $Report.'Folder Name' = $FolderName
9  $Report.'Full Path' = $ParentPath
10 #finally, call the report
11 $Report
12 }

Here is a brief explanation of each line of the code:

  1. In line 1, I saved the result of the Get-ChildItem command in the dirs variable.
  2. Then, in line 2, I used the dirs variable in my ForEach statement loop. Every other line of code is within the ForEach statement loop.
  3. In line 3, I saved the result of “Split-Path -Parent $dir.fullname” in the ParentPath variable. The command “Split-Path -Parent $dir.fullname” removes the name of the directory from the FullName property. I used this property in an earlier example.
  4. Then, in line 4, I saved the command $dir.Name in the FolderName variable. The command $dir.Name extracts the folder name of the folder.
  5. Moving on to line 5, I added a comment providing information. Any comment you add in a PowerShell script does not execute.
  6. In line 6, I used the Select-Object command to create an empty report with two properties – “Folder Name” and “Full Path.” Then, I saved the result of the Select-Object command on the Report variable.
  7. Then, in line 7, I added another comment explaining what I intend to achieve with the codes below the comment.
  8. In pine 8, I linked the “Folder Name” property of the Select-Object command saved in the Report variable to information saved in the FolderName variable. The command in line 8 adds the information saved in the FolderName variable into the “Folder Name” property of the Select-Object command.
  9. The command in line 9 is similar to that in line 8. However, in line 9, I link the “Full Path” property to the information saved in the ParentPath variable.
  10. Line 10 is a comment.
  11. Then, in line 11, I call the report.
  12. Finally, in line 12, I close (with }) the ForEach loop statement I opened (with {) in line 2.

How To Use The “Recurse” And “Depth” Parameters In PowerShell Get-Childitem

You specify the Recurse parameter when you want PowerShell Get-Childitem to return results from a specified path and all sub-folders. When you specify the Recurse parameter, Get-Childitem checks all sub-folders by default.

However, if you want Get-Childitem to check up to a particular sub-folder level, you specificity the Depth parameter.

I have a folder called “Log Files” located in drive D on my laptop. I created three folders under “Log Files” to show you how this works – see the screenshot below.

How To Use The "Recurse" And "Depth" Parameters In PowerShell Get-Childitem

First of all, I will run the Get-Childitem command with the Recurse parameter.

Get-Childitem "D:\Log Files" -Recurse

PowerShell Get-Childitem will display information about all the folders in “Log Files” and all sub-folders.

But if I want Get-Childitem to go just 1 level deep, I will include the Depth parameter as shown in the command below…

Get-Childitem "D:\Log Files" -Recurse -Depth 1

This time, the command will return information about “Log Files” and only the first level sub-folders.

How To Order The Output Of PowerShell Get-Childitem By Date, Name, Size, Or File Extension

When you run the Get-Childitem command, it returns a number of properties. Some of the properties returned are Date, Name, Size (Length), and File Extension.

You can order the output of PowerShell Get-Childitem by any of these properties.

To kick the example in this sub-section off, the command below will order the result of Get-Childitem by Name.

Get-ChildItem -Path 'D:\PowerShell Scripts\*' -File | Sort-Object -Property Name | Select-Object Name, LastWriteTime, Extension

The command that does the sorting is the Sort-Object command. You can see in the screenshot below that the results are ordered by the name of the folders.

How To Order The Output Of PowerShell Get-Childitem By Date, Name, Size, Or File Extension

Similarly, I can order the result by the last time the folders or files were updated. The property with this information is called LastWriteTime.

So, here is the command that orders the result of Get-Childitem by date.

Get-ChildItem -Path 'D:\PowerShell Scripts\*' -File | Sort-Object -Property LastWriteTime | Select-Object Name, LastWriteTime, Extension

Now, the Get-ChildItem command has ordered the result by the date created – starting from the older item.

Similarly, to order the results of PowerShell Get-Childitem by Size or File Extension, I’ll use the following commands:

Get-ChildItem -Path 'D:\PowerShell Scripts\*' -File | Sort-Object -Property Length | Select-Object Name, Length

The command displays the file with the smallest size first.

Get-ChildItem -Path 'D:\PowerShell Scripts\*' -File | Sort-Object -Property Extension | Select-Object Name, Extension 

This time around, Get-ChildItem ordered the result by file Extension.

PowerShell Get-Childitem: Frequently Asked Questions

1. What Is The Get-ChildItem Command In PowerShell?

The Get-ChildItem returns the items and child items in one or more specified locations. You can use Get-ChildItem to list items and child items in a file system directory, registry hive, or certificate store.

2. How Do You Get The Full Path With Get-ChildItem?

To get the full path of items with the Get-ChildItem command, return the “FullName” property. For example, the command below returns the full path of all items (files and folders) in the path ‘D:\PowerShell Scripts’

Get-ChildItem -Path ‘D:\PowerShell Scripts’ -Directory | Select-Object Name, “FullName”

3. How Do I Get Only Files Using Get-ChildItem?

To get only files using Get-ChildItem, specify the File parameter. For example, the command below returns only files.

Get-ChildItem –File -Path ‘D:\PowerShell Scripts’

4. How Do I Get A List Of Directories In PowerShell?

To get a list of directories in PowerShell, specify the Directory parameter in a Get-ChildItem command. Here is an example:

Get-ChildItem –Directory-Path ‘D:\PowerShell Scripts’

5. How Do I Get A List Of Files In A Directory And Subfolders In PowerShell?

To get a list of files in a directory and subfolders in PowerShell, run the Get-ChildItem command. Then, specify the File and the Recurse parameters.

The File parameter tells PowerShell Get-Childitem to return only files. On the other hand, the Recurse parameter returns items from all sub-folders.

PowerShell Get-Childitem: My Final Thoughts

The Get-Childitem Cmdlet is one of the most important Cmdlets in PowerShell. As you have seen in this guide, you can use this Cmdlet to return information about folders.

In addition to folders, you can also use Get-Childitem to list information about registry hives.

Kindly vote Yes to the “Was this post Helpful” question below if you found this article valuable.

Alternatively, you could ask a question, leave a comment or provide more feedback with the “Leave a Reply” form found at the end of this page.

Finally, for more PowerShell tech Itechguides, visit our Windows PowerShell Explained page. You may also find our Windows PowerShell How-To Guides page valuable.

References And Further Reading

  1. ForEach with Multiple Variables – Powershell – Stack Overflow
  2. Creating an array from the Get-ChildItem cmdlet (microsoft.com)
Leave a Reply

Your email address will not be published.

You May Also Like