Rename Files and Folders in PowerShell with Rename-Item

2.4K

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.

PowerShell version. The examples in our article work in both Windows PowerShell 5.1 and PowerShell 7.x on Windows. We recommend PowerShell 7.x for new scripts and automation. PowerShell 7.x is cross-platform, but some examples in our article, such as Windows Registry operations and Windows-specific environment variables, apply only to Windows.

Rename-Item basic syntax

The basic syntax of the Rename-Item cmdlet is:

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

• -Path — specifies the path to the file system object (file or folder) or registry item to rename. The path can be local or a UNC/network path. Rename-Item does not provide a -ComputerName parameter; to run the rename operation on a remote machine, you should use PowerShell Remoting with Invoke-Command.
• -NewName — set a new name for an object.

For example, renaming a file:

Rename-Item -Path C:\PS\app_report.docx -NewName report2026.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 report2026.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 report2026.docx -Confirm

ren is an alias for Rename-Item in PowerShell. Do not confuse it with the CMD ren command: although they use the same alias name, their syntax and wildcard behavior differ. For example, CMD supports commands such as ren *.txt *.bak, while the PowerShell ren alias does not use the CMD wildcard-renaming syntax. You should use Rename-Item with Get-ChildItem or an expression with -NewName for bulk renaming in PowerShell.

Here is an example of using the short command to rename a file:

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

In case the new filename is already being used by another object, the rename operation fails with the error:

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

Note that the -Force parameter does not overwrite an existing file/resolve a name conflict. You can use it when renaming hidden/read-only items, where the provider supports the operation.

Also, 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\report2026.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 renames registry keys; it does not rename registry values. To rename a registry value, you need to use the Rename-ItemProperty cmdlet instead. Rename-Item also does not change the data stored in registry values. 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

Permissions. Keep in mind that modifying keys under HKEY_LOCAL_MACHINE typically requires an elevated PowerShell session. You need to run PowerShell as Administrator when the current account does not have the required permissions.

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

Bulk rename files with Rename-Item

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 rename the .jpg extensions of all matching files to .png, run the following command:

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

Important. Keep in mind that changing a file extension does not convert the file format. The example above only renames the file from .jpg to .png; the file contents remain JPEG. In order to convert an image from JPEG to PNG, you should use an image conversion tool rather than Rename-Item.

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 PowerShell’s ShouldProcess functionality through the -WhatIf and -Confirm common parameters. For bulk renames, you should use -WhatIf during testing to verify the generated names before applying changes.

Add prefix or suffix to multiple files

Another common task is to add a prefix/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 the following PowerShell script:

$suffix = "_$([System.Environment]::MachineName)"

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

    if ($_.BaseName.EndsWith($suffix, [System.StringComparison]::OrdinalIgnoreCase)) {
        return
    }

    $newName = $_.BaseName + $suffix + $_.Extension

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

Important. Our example above uses -WhatIf, so it only previews the proposed rename operations and does not actually rename any files. You need to review the output first, then remove -WhatIf from the Rename-Item command to perform the rename.

The -LiteralPath parameter treats the file path literally, so characters such as [ and ] in file names are not interpreted as wildcard characters. The EndsWith() check prevents the script from appending the suffix to files that have already been renamed.

Also, note that when you are performing bulk renaming operations (especially when adding prefixes/suffixes), you may encounter a Windows path length limitation. Windows historically imposed a MAX_PATH limit of 260 characters for many Win32 APIs. Modern Windows versions support longer paths for apps that are configured and designed to use long-path support.

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

$_.BaseName + "_" + [System.Environment]::MachineName + $_.Extension

This increases the file name length and can result in path-length-related errors when the resulting path exceeds the limits supported by the underlying Windows API/app.

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

Newer Windows versions can support paths longer than the traditional 260-character MAX_PATH limit when long-path support is enabled and the app/API supports it. You can enable long paths through the Enable Win32 long paths Group Policy setting or the LongPathsEnabled registry value. However, this does not guarantee long-path support for every app/PowerShell case.

PowerShell version matters. PowerShell 7 generally provides better support for long paths through its modern .NET runtime, while Windows PowerShell 5.1 can still encounter limitations depending on the underlying Windows API and app behavior. In case your scripts must handle very long paths, you need to test them specifically in the PowerShell version and environment where they will run.

Also consider keeping directory structures reasonably short and avoiding unnecessarily long generated file names when performing reliable bulk-renaming operations.