Share via

Rename-Item

  • Reference
Module:
Microsoft.PowerShell.Management

Renames an item in a PowerShell provider namespace.

Syntax

Rename-Item
      [-Path] <String>
      [-NewName] <String>
      [-Force]
      [-PassThru]
      [-Credential <PSCredential>]
      [-WhatIf]
      [-Confirm]
      [-UseTransaction]
      [<CommonParameters>]
Rename-Item
      -LiteralPath <String>
      [-NewName] <String>
      [-Force]
      [-PassThru]
      [-Credential <PSCredential>]
      [-WhatIf]
      [-Confirm]
      [-UseTransaction]
      [<CommonParameters>]

Description

The Rename-Item cmdlet changes the name of a specified item. This cmdlet does not affect the content of the item being renamed.

You can't use Rename-Item to move an item, such as by specifying a path together with the new name. To move and rename an item, use the Move-Item cmdlet.

Examples

Example 1: Rename a file

This command renames the file daily_file.txt to monday_file.txt.

Rename-Item -Path "c:\logfiles\daily_file.txt" -NewName "monday_file.txt"

Example 2: Rename and move an item

You can't use Rename-Item to both rename and move an item. Specifically, you can't supply a path for the value of the NewName parameter, unless the path is identical to the path specified in the Path parameter. Otherwise, only a new name is permitted.

This example attempts to rename the project.txt file in the current directory to old-project.txt in the D:\Archive directory. The result is the error shown in the output.

Rename-Item -Path "project.txt" -NewName "d:\archive\old-project.txt"

Rename-Item : can't rename because the target specified represents a path or device name.
At line:1 char:12
+ Rename-Item <<<<  -path project.txt -NewName d:\archive\old-project.txt
+ CategoryInfo          : InvalidArgument: (:) [Rename-Item], PS>  Move-Item -Path "project.txt" -De
stination "d:\archive\old-project.txt"

Example 3: Rename a registry key

This example renames a registry key from Advertising to Marketing. When the command is complete, the key is renamed, but the registry entries in the key are unchanged.

Rename-Item -Path "HKLM:\Software\MyCompany\Advertising" -NewName "Marketing"

Example 4: Rename multiple files

This example renames all the *.txt files in the current directory to *.log.

Get-ChildItem *.txt

Directory: C:\temp\files

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        10/3/2019   7:47 AM           2918 Friday.TXT
-a----        10/3/2019   7:46 AM           2918 Monday.Txt
-a----        10/3/2019   7:47 AM           2918 Wednesday.txt

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

Directory: C:\temp\files

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        10/3/2019   7:47 AM           2918 Friday.log
-a----        10/3/2019   7:46 AM           2918 Monday.log
-a----        10/3/2019   7:47 AM           2918 Wednesday.log

The Get-ChildItem cmdlet gets all the files in the current folder that have a .txt file extension then pipes them to Rename-Item. The value of NewName is a script block that runs before the value is submitted to the NewName parameter.

In the script block, the $_ automatic variable represents each file object as it comes to the command through the pipeline. The script block uses the -replace operator to replace the file extension of each file with .log. Notice that matching using the -replace operator is not case sensitive.

Parameters

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Credential

Note

This parameter is not supported by any providers installed with PowerShell. To impersonate another user, or elevate your credentials when running this cmdlet, use Invoke-Command.

Type:PSCredential
Position:Named
Default value:Current user
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Force

Forces the cmdlet to rename items that can't otherwise be changed, such as hidden or read-only files or read-only aliases or variables. The cmdlet can't change constant aliases or variables. Implementation varies from provider to provider. For more information, see about_Providers.

Even using the Force parameter, the cmdlet can't override security restrictions.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-LiteralPath

Specifies a path to one or more locations. The value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape sequences.

For more information, see about_Quoting_Rules.

Type:String
Aliases:PSPath
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-NewName

Specifies the new name of the item. Enter only a name, not a path and name. If you enter a path that differs from the path that is specified in the Path parameter, Rename-Item generates an error. To rename and move an item, use Move-Item.

You can't use wildcard characters in the value of the NewName parameter. To specify a name for multiple files, use the Replace operator in a regular expression. For more information about the Replace operator, see about_Comparison_Operators.

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-PassThru

Returns an object that represents the item to the pipeline. By default, this cmdlet does not generate any output.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Path

Specifies the path of the item to rename.

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-UseTransaction

Includes the command in the active transaction. This parameter is valid only when a transaction is in progress. For more information, see about_Transactions.

Type:SwitchParameter
Aliases:usetx
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Inputs

String

You can pipe a string that contains a path to this cmdlet.

Outputs

None or an object that represents the renamed item.

This cmdlet generates an object that represents the renamed item, if you specify the PassThru parameter. Otherwise, this cmdlet does not generate any output.

Notes

Rename-Item is designed to work with the data exposed by any provider. To list the providers available in your session, type Get-PsProvider. For more information, see about_Providers.