In this beginner's guide, you will learn how to rename files with PowerShell. I will demonstrate how to list files with the Get-ChildItem cmdlet, and then I will discuss a few examples of renaming files with the Rename-Item cmdlet.
Latest posts by Dan Greenhaus (see all)
Contents of this article

Get-ChildItem ^

Get-ChildItem, or GCI for short, does a very basic task: it returns the list of items in one or more locations. For DOS users, it's the equivalent of DIR, and for Linux users, it's the equivalent of ls, both of which are also aliases for the Get-ChildItem cmdlet in PowerShell.

GCI can be used to retrieve a list of files in a specified folder, or child items in a registry key. It can then either return the output to your screen or save it as a variable. GCI also has several useful parameters, but the four we will be discussing are -recurse, -depth, -include, and -exclude.

The -recurse parameter is used when you want to include every child item, including every subfolder and item in every subfolder. The -depth parameter is similar to -recurse; however, you can specify the number of subfolder levels you want to return. Here is an example:

Get-ChildItem -Path C:\Parent -Depth 2 

This command will return all child items for C:\Parent and any child items within their subdirectories but not any deeper.

With -include, you can get results based on certain criteria:

Get-ChildItem -Path C:\Test\* -Include *.txt 

In this example, we search for all files and folders in C:\Test but only include those files that have a .txt extension.

The -exclude parameter allows you to filter out the results based on the provided criteria.

Get-ChildItem -Path C:\TestFolder\* -Exclude A*

Here, we search for all files and folders but omit any results that start with A.

An alternative to using the -include and -exclude parameters is to send the results down the pipeline, and pipe them to the Where-object cmdlet. This allows you to take advantage of Where-object's ability to filter based on more object properties than just file names.

Rename-Item ^

With the Rename-Item cmdlet, you can change the name of a specified item without changing its contents. This can be done with a file, directory, or registry key. Important parameters are -path and -newname. The -path parameter specifies the location of the object you are looking to rename. Use -newname to specify the new name of the object.

Rename-Item -Path "c:\testlocation\test_file.txt" -NewName "mytest_file.txt" 

This command takes the test_file.txt located in c:\testlocation and renames the file to mytest_file.txt.

While using the rename-item parameter on a single file might not be efficient, when you pair it with the results from a Get-ChildItem -include or Get-ChildItem | Where-object, you can make many repetitive changes to multiple file names using a single line.

Get-ChildItem *.txt | Rename-Item -NewName { $_.Name -replace '.txt','.log' } 

The example above replaces the .txt extension of all files in the current folder with the .log extension.

You can easily accomplish these tasks with File Explorer. I will now give you a real-world renaming example where PowerShell shines. A user came to me with an issue. One of our automated processes generated a daily file, and he needed to manually rename it so it could be processed appropriately. This had been discovered a week previously, so he had an additional phrase added to the file name in 300 files and didn't want to manually change every one of them.

File names containing a certain phrase

File names containing a certain phrase

This is my solution for renaming the files:

#to remove a phrase that has been appended to the end of a bunch of files
$dir = "<insert folder path here>" 
$phrase = " AddlCharsToBeRemoved" #<replace this with phrase you are looking to remove>, including any spaces
$length=$phrase.Length #this obtains the length of the phrase that is to be removed
Get-ChildItem $dir -Recurse| Where-Object { $_.Name -like "*$phrase*" } | Rename-Item -NewName { $,$_.BaseName.length-$length)+$_.Extension}# -WhatIf -verbose
Renaming files with a PowerShell script

Renaming files with a PowerShell script

This script is made to be reusable, which is why it doesn't replace the phrase to be removed, but simply shortens the base name by the length of characters in the phrase, and then creates the new filename. The where-object parameter ensures that only the files that contain the phrase are modified.

I also have two parameters commented out: -whatif and -verbose. Both of these are parameters in Rename-Item, and are important during script development and testing. The -whatif parameter shows what would happen if the cmdlet ran. The cmdlet is not run.

Subscribe to 4sysops newsletter!

The -verbose parameter is not a specific rename-item parameter; however, it is a common parameter that can be used with any cmdlet. It's not implemented by the cmdlet developer but rather by PowerShell itself. The parameter displays detailed information about the operation done by the command. This allows you to view exactly what the command is doing, which is helpful in troubleshooting when a script isn't doing exactly what you expect it to do.


Leave a reply

Please enclose code in pre tags

Your email address will not be published. Required fields are marked *


© 4sysops 2006 - 2021


Please ask IT administration questions in the forums. Any other messages are welcome.


Log in with your credentials


Forgot your details?

Create Account