Rename Files and Folders in PowerShell with Rename-Item

2.3K

The Rename-Item cmdlet is used to rename an existing file, directory, or registry item without changing its contents. In this article, we’ll explore common use cases for the Rename-Item cmdlet, from renaming individual files or folders to batch scripts for changing file names, file extensions, and more.

Rename-Item basic syntax

The basic syntax of the Rename-Item cmdlet is:

Rename-Item -Path <existing item> -NewName <new name>

• -Path – full path to the file system object (folder, file) or registry item to rename. It can be a local or remote path.
• -NewName – set a new name for an object.

For example, renaming a file:

Rename-Item -Path C:\PS\app_report.docx -NewName report2025.docx

Note that the -WhatIf parameter allows you to preview the operation without actually renaming the file. This is especially useful in production environments:

Rename-Item -Path C:\PS\app_report.docx -NewName report2025.docx -WhatIf

Also, you can use the -Confirm parameter to prompt the user before executing the rename operation:

Rename-Item -Path C:\PS\app_report.docx -NewName report2025.docx -Confirm

ren is an alias for Rename-Item in PowerShell, but behavior may differ from CMD ren command when you are using it in scripts/cross-shell contexts. Here is an example of using the short command to rename a file:

ren C:\ps\app_report.docx report2025.docx

If the new filename is already being used by another object, an error will occur:

Rename-Item : Cannot create a file when that file already exists.

To rename a file with a hidden or read-only attribute set, add the -Force parameter.

Keep in mind that Rename-Item does not output the renamed object unless -PassThru is used. Here is an example:

Rename-Item file.txt new.txt -PassThru

NewName parameter accepts only file names

Also note that the NewName parameter accepts only file names. The Rename-Item cmdlet doesn’t allow to rename a file and move it to a different directory. Therefore, if you specify a path in the new filename, the command returns an error:

Rename-Item -Path C:\PS\app_report.docx -NewName c:\docs\report2025.docx

Rename-Item : Cannot rename the specified target, because it represents a path or device name.

Rename registry items with Rename-Item

Rename-Item works on registry keys via the PowerShell Registry provider. Note that Rename-Item does not modify the content of registry values/file contents. It only renames items within the same PowerShell provider and the same location scope. It cannot move objects between different locations (such as between registry hives/between different drives). Here is an example:

Rename-Item HKLM:\SOFTWARE\CorpApp_test -NewName CorpApp

In order to move and rename at the same time, use Move-Item instead of Rename-Item:

Move-Item file.txt C:\NewFolder\newname.txt

The most common use of the Rename-Item cmdlet is to perform bulk renaming of files in a directory. For mass renaming of objects, a pipeline with Get-ChildItem is usually used.

For example, to change the extensions of all files in a directory from ‘.jpg’ to ‘.png’, run:

Get-ChildItem -Path C:\PS\*.jpg -File |
Rename-Item -NewName { $_.Name -replace '\.jpg$', '.png' } -WhatIf -Verbose

Note that when you are performing bulk rename operations, you should always use -WhatIf first to validate results before applying changes.

Note that the -Newname parameter does not accept wildcards, so we used an expression with the -replace operator to generate a new filename.

Note. Rename-Item supports both -WhatIf and -Confirm because it implements ShouldProcess. It is is required for safe operations in PowerShell cmdlets that modify system state.

Add prefix or suffix to multiple files

Another common task is to add a prefix or suffix to multiple files. For example, suppose you have a directory of log files, and you want to append the current host name as a suffix to each file before sending them to the log collector. To accomplish this task, use this PowerShell one-liner with Rename Item:

Get-ChildItem "C:\PS\Logs" -Filter "log_*.txt" | ForEach-Object {

    $newName = $_.BaseName + '_' + $env:COMPUTERNAME + $_.Extension

    $newPath = Join-Path $_.DirectoryName $newName

    if ($newPath.Length -gt 260) {
        Write-Warning "Skipping file due to long path: $newPath"
        return
    }

    Rename-Item -Path $_.FullName -NewName $newName -WhatIf
}

Note that when you are performing bulk renaming operations (especially when adding prefixes/suffixes), you may encounter a Windows path length limitation.

By default, Windows historically supports a maximum path length of approximately 260 characters (MAX_PATH). This includes the full directory path plus the file name.

For example, you added a suffix like the machine name:

$_.BaseName + "_" + $env:COMPUTERNAME + $_.Extension

This can significantly increase file name length and cause errors such as:

“The specified path is too long”

Note that this problem is especially common in deep directory structures (e.g. nested log folders), files with already long names, batch renaming operations.

To solve this issue, you should consider shortening suffix values, reducing folder depth, enabling long path support in Windows (Group Policy/registry).