Copy-Item

Reference

Module:: Microsoft.PowerShell.Management

Copies an item from one location to another.

Syntax

Copy-Item
    [-Path] <String[]>
    [[-Destination] <String>]
    [-Container]
    [-Force]
    [-Filter <String>]
    [-Include <String[]>]
    [-Exclude <String[]>]
    [-Recurse]
    [-PassThru]
    [-Credential <PSCredential>]
    [-WhatIf]
    [-Confirm]
    [-UseTransaction]
    [-FromSession <PSSession>]
    [-ToSession <PSSession>]
    [<CommonParameters>]

Copy-Item
    -LiteralPath <String[]>
    [[-Destination] <String>]
    [-Container]
    [-Force]
    [-Filter <String>]
    [-Include <String[]>]
    [-Exclude <String[]>]
    [-Recurse]
    [-PassThru]
    [-Credential <PSCredential>]
    [-WhatIf]
    [-Confirm]
    [-UseTransaction]
    [-FromSession <PSSession>]
    [-ToSession <PSSession>]
    [<CommonParameters>]

Copy-Item
    [-Path] <String[]>
    [[-Destination] <String>]
    [-Container]
    [-Force]
    [-Filter <String>]
    [-Include <String[]>]
    [-Exclude <String[]>]
    [-Recurse]
    [-PassThru]
    [-Credential <PSCredential>]
    [-WhatIf]
    [-Confirm]
    [-UseTransaction]
    [<CommonParameters>]

Copy-Item
    -LiteralPath <String[]>
    [[-Destination] <String>]
    [-Container]
    [-Force]
    [-Filter <String>]
    [-Include <String[]>]
    [-Exclude <String[]>]
    [-Recurse]
    [-PassThru]
    [-Credential <PSCredential>]
    [-WhatIf]
    [-Confirm]
    [-UseTransaction]
    [<CommonParameters>]

Description

The Copy-Item cmdlet copies an item from one location to another location in the same namespace. For instance, it can copy a file to a folder, but it can't copy a file to a certificate drive.

This cmdlet doesn't cut or delete the items being copied. The particular items that the cmdlet can copy depend on the PowerShell provider that exposes the item. For instance, it can copy files and directories in a file system drive and registry keys and entries in the registry drive.

This cmdlet can copy and rename items in the same command. To rename an item, enter the new name in the value of the Destination parameter. To rename an item and not copy it, use the Rename-Item cmdlet.

Examples

Example 1: Copy a file to the specified directory

This example copies the mar1604.log.txt file to the C:\Presentation directory. The original file isn't deleted.

Copy-Item "C:\Wabash\Logfiles\mar1604.log.txt" -Destination "C:\Presentation"

Example 2: Copy directory contents to an existing directory

This example copies the contents of the C:\Logfiles directory into the existing C:\Drawings directory. The Logfiles directory isn't copied.

If the Logfiles directory has files in subdirectories, those subdirectories are copied with their file trees intact. By default, the Container parameter is set to True, which preserves the directory structure.

Copy-Item -Path "C:\Logfiles\*" -Destination "C:\Drawings" -Recurse

Note

If the path C:\Drawings doesn't exist the cmdlet copies all the files from the Logfiles folder tree into a single folder C:\Drawings, overwriting any files with the same name.

Example 3: Copy directory and contents to a new directory

This example copies the contents of the C:\Logfiles source directory and creates a new destination directory. The new destination directory, \Logs is created in C:\Drawings.

To include the source directory's name, copy to an existing destination directory as shown in Example 2. Or, name the new destination directory with the same as the source directory.

Copy-Item -Path "C:\Logfiles" -Destination "C:\Drawings\Logs" -Recurse

Note

If the Path includes \*, all the directory's file contents, including the subdirectory trees, are copied to the new destination directory. For example:

Copy-Item -Path "C:\Logfiles\*" -Destination "C:\Drawings\Logs" -Recurse

Example 4: Copy a file to the specified directory and rename the file

This example uses the Copy-Item cmdlet to copy the Get-Widget.ps1 script from the \\Server01\Share directory to the \\Server12\ScriptArchive directory. As part of the copy operation, the command changes the item name from Get-Widget.ps1 to Get-Widget.ps1.txt, so it can be safely attached to email messages.

Copy-Item "\\Server01\Share\Get-Widget.ps1" -Destination "\\Server12\ScriptArchive\Get-Widget.ps1.txt"