PowerShell Rename-Item: Syntax, Examples & Troubleshooting

powershell rename file is the Rename-Item cmdlet that renames a file or folder without moving it. Use:

Rename-Item -Path "C:report.txt" -NewName "report_backup.txt" -WhatIf

Syntax

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

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

# Alias: ren, rni
Get-Alias -Definition Rename-Item

Tested on Windows 10 22H2 with PowerShell 7.4.

Options and Flags

Usage Examples

Example 1: Rename a single file

Rename-Item -Path "C:Reportssales_2024.csv" -NewName "sales_2024_backup.csv" -WhatIf
# Remove -WhatIf to execute

Renames the file in the same directory. The -WhatIf switch displays the intended change without modifying the file system. Always run with -WhatIf to verify the target file exists and the new name is correct. This cmdlet does not affect the content of the item being renamed.

Example 2: Bulk rename – change file extension

Get-ChildItem -Path "C:Logs*.log" | ForEach-Object {
    Rename-Item -Path $_.FullName -NewName ($_.Name -replace '.log$', '.txt') -WhatIf
}

Changes the extension of all .log files to .txt. The -replace operator uses regex; the $ anchor ensures only the final extension is matched. Note that -replace is not case sensitive. This method preserves the file name and location. After verification, remove -WhatIf.

Example 3: Bulk rename – sanitise filenames

Get-ChildItem -Path "C:Books*.pdf" -Recurse | ForEach-Object {
    $newName = $_.Name
    $newName = $newName -replace "[()']", ''   # remove brackets and apostrophes
    $newName = $newName -replace "s+", '-'    # replace spaces with hyphen
    $newName = $newName -replace '-+', '-'     # collapse multiple hyphens
    $newName = $newName.ToLower()
    Rename-Item -Path $_.FullName -NewName $newName -WhatIf
}

Cleans up book PDFs from publishers that contain special characters and irregular spacing. The script processes all subdirectories (-Recurse), removes parentheses and apostrophes, normalises spaces and hyphens, and forces lowercase. Always preview with -WhatIf.

Troubleshooting & Common Errors

Frequently Asked Questions

Rename-Item -Path "C:log.txt" -NewName "log_old.txt"
Move-Item -Path "C:log.txt" -Destination "D:archivelog_archived.txt"

Rename-Item -Path "*.tmp" -NewName { $_.Name -replace '.tmp$','.bak' } -PassThru | Set-ItemProperty -Name IsReadOnly -Value $true

# Force rename even if read-only (requires modify permission)
Rename-Item -Path "C:file.txt" -NewName "file_renamed.txt" -Force
# Find locked processes (Sysinternals handle.exe or PowerShell)
Get-Process | Where-Object { $_.Modules.FileName -like "*file.txt*" }

# Linux
Rename-Item -Path "/home/user/report.log" -NewName "report_old.log"
# macOS
Rename-Item -Path "/Users/user/data.csv" -NewName "data_backup.csv"

# Add prefix "archive_" to all .log files
Get-ChildItem "*.log" | Rename-Item -NewName { "archive_" + $_.Name }
# Replace spaces with underscores using regex
Get-ChildItem "* *.txt" | Rename-Item -NewName { $_.Name -replace ' ', '_' }