Copy-Item
Copies an item from one location to another.
Copy-Item [-Path*] <String[]> [[-Destination] [<String>]] [-Container] [-Credential [<PSCredential>]] [-Exclude[<String[]>]] [-Filter [<String>]] [-Force] [-FromSession [<PSSession>]] [-Include [<String[]>]] [-PassThru][-Recurse] [-ToSession [<PSSession>]] [-Confirm] [-WhatIf] [-UseTransaction [<SwitchParameter>]][<CommonParameters>]
Copy-Item [[-Destination] [<String>]] [-Container] [-Credential [<PSCredential>]] [-Exclude [<String[]>]] [-Filter[<String>]] [-Force] [-FromSession [<PSSession>]] [-Include [<String[]>]] [-PassThru] [-Recurse] [-ToSession[<PSSession>]] -LiteralPath* <String[]> [-Confirm] [-WhatIf] [-UseTransaction [<SwitchParameter>]][<CommonParameters>]
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 cannot copy a file to a certificate drive.
This cmdlet does not cut or delete the items being copied. The particular items that the cmdlet can copy depend on the Windows 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.
Parameters |
---|
-Container [<SwitchParameter>]
|
-Credential [<PSCredential>]
|
-Destination [<String>]
|
-Exclude [<String[]>]
|
-Filter [<String>]
|
-Force [<SwitchParameter>]
|
-FromSession [<PSSession>]
|
-Include [<String[]>]
|
-LiteralPath <String[]>
|
-PassThru [<SwitchParameter>]
|
-Path <String[]>
|
-Recurse [<SwitchParameter>]
|
-ToSession [<PSSession>]
|
-Confirm [<SwitchParameter>]
|
-WhatIf [<SwitchParameter>]
|
-UseTransaction [<SwitchParameter>]
|
<CommonParameters>
|
Inputs
System.String
You can pipe a string that contains a path to this cmdlet.
Outputs
None or an object representing the copied item.
When you use the PassThru parameter, this cmdlet returns an object that represents the copied item. Otherwise, this cmdlet does not generate any output.
Examples
- Copy a file to the specified directory:
PS C:> Copy-Item "C:WabashLogfilesmar1604.log.txt" -Destination "C:Presentation"
This command copies the mar1604.log.txt file to the C:Presentation directory. The command does not delete the original file.
- Copy the contents of a directory to another directory:
PS C:> Copy-Item "C:Logfiles" -Destination "C:Drawings" -Recurse
This command copies the entire contents of the Logfiles directory into the Drawings directory. If the LogFiles directory contains files in subdirectories, those subdirectories will be copied with their file trees intact. The Container parameter is set to true by default. This preserves the directory structure.
- Copy the contents of a directory to another directory and create the destination directory if it does:
not exist PS C:> Copy-Item C:Logfiles -Destination C:DrawingsLogs -Recurse
This command copies the contents of the C:Logfiles directory to the C:DrawingsLogs directory. It creates the Logs subdirectory if it does not already exist.
- Copy a file to the specified directory and rename the file:
PS C:> Copy-Item "\Server01ShareGet-Widget.ps1" -Destination "\Server12ScriptArchiveGet-Widget.ps1.txt"
This command uses the Copy-Item cmdlet to copy the Get-Widget.ps1 script from the \Server01Share directory to the \Server12ScriptArchive directory. As part of the copy operation, the command also changes the item name from Get-Widget.ps1 to Get-Widget.ps1.txt, so it can be attached to email messages.
- Copy a file to a remote computer:
PS C:> $Session = New-PSSession -ComputerName "Server01" -Credential "ContosoPattiFul" PS C:> Copy-Item "D:Folder001test.log" -Destination "C:Folder001_Copy" -ToSession $Session
The first command creates a session to the remote computer named Server01 with the credential of ContosoPattiFul and stores the results in the variable named $Session.
The second command uses the Copy-Item cmdlet to copy test.log from the D:Folder001 folder to the C:Folder001_Copy folder on the remote computer using the session information stored in the $Session variable. This command does not delete the original file.
- Copy the entire contents of a folder to a remote computer:
PS C:> $Session = New-PSSession -ComputerName "Server02" -Credential "ContosoPattiFul" PS C:> Copy-Item "D:Folder002" -Destination "C:Folder002_Copy" -ToSession $Session
The first command creates a session to the remote computer named Server01 with the credential of ContosoPattiFul and stores the results in the variable named $Session.
The second command uses the Copy-Item cmdlet to copy the entire contents from the D:Folder002 folder to the C:Folder002_Copy directory on the remote computer using the session information stored in the $Session variable. The subfolders will be copied with their file trees intact.
- Recursively copy the entire contents of a folder to a remote computer:
PS C:> $Session = New-PSSession -ComputerName "Server04" -Credential "ContosoPattiFul" PS C:> Copy-Item "D:Folder003" -Destination "C:Folder003_Copy" -ToSession $Session -Recurse
The first command creates a session to the remote computer named Server01 with the credential of ContosoPattiFul and stores the results in the variable named $Session.
The second command uses the Copy-Item cmdlet to copy the entire contents from the D:Folder003 folder to the C:Folder003_Copy directory on the remote computer using the session information stored in the $Session variable. The subfolders will be copied with their file trees intact. Since this command uses the Recurse parameter, the operation will create the Folder003_Copy folder if it does not already exist.
- Copy a file to a remote computer and then rename the file:
PS C:> $Session = New-PSSession -ComputerName "Server04" -Credential "ContosoPattiFul" PS C:> Copy-Item "D:Folder004scriptingexample.ps1" -Destination "C:Folder004_Copyscriptingexample_copy.ps1" -ToSession $Session
The first command creates a session to the remote computer named Server01 with the credential of ContosoPattiFul and stores the results in the variable named $Session.
The second command uses the Copy-Item cmdlet to copy scriptingexample.ps1 from the D:Folder004 folder to the C:Folder004_Copy folder on the remote computer using the session information stored in the $Session variable. As part of the copy operation, the command also changes the item name from scriptingexample.ps1 to scriptingexample_copy.ps1, so it can be attached to email messages. This command does not delete the original file.
- Copy a remote file to the local computer:
PS C:> $Session = New-PSSession -ComputerName "Server01" -Credential "ContosoPattiFul" PS C:> Copy-Item "C:MyRemoteDatatest.log" -Destination "D:MyLocalData" -FromSession $Session
The first command creates a session to the remote computer named Server01 with the credential of ContosoPattiFul and stores the results in the variable named $Session.
The second command uses the Copy-Item cmdlet to copy test.log from the remote C:MyRemoteData to the local D:MyLocalData folder using the session information stored in the $Session variable. This command does not delete the original file.
- Copy the entire contents of a remote folder to the local computer:
PS C:> $Session = New-PSSession -ComputerName "Server01" -Credential "ContosoPattiFul" PS C:> Copy-Item "C:MyRemoteDatascripts" -Destination "D:MyLocalData" -FromSession $Session
The first command creates a session to the remote computer named Server01 with the credential of ContosoPattiFul and stores the results in the variable named $Session.
The second command uses the Copy-Item cmdlet to copy the entire contents from the remote C:MyRemoteDatascripts folder to the local D:MyLocalData folder using the session information stored in the $Session variable. If the scripts folder contains files in subfolders, those subfolders will be copied with their file trees intact.
- Recursively copy the entire contents of a remote folder to the local computer:
PS C:> $Session = New-PSSession -ComputerName "Server01" -Credential "ContosoPattiFul" PS C:> Copy-Item "C:MyRemoteDatascripts" -Destination "D:MyLocalDatascripts" -FromSession $Session
The first command creates a session to the remote computer named Server01 with the credential of ContosoPattiFul and stores the results in the variable named $Session.
The second command uses the Copy-Item cmdlet to copy the entire contents from the remote C:MyRemoteDatascripts folder to the local D:MyLocalDatascripts folder using the session information stored in the $Session variable. Since this command uses the Recurse parameter, the operation will create the scripts folder if it does not already exist .If the scripts folder contains files in subfolders, those subfolders will be copied with their file trees intact.
Additional Notes
This cmdlet is similar to the cp or copy commands in other shells. This cmdlet 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.
Related Links
Clear-Item
Get-Item
Invoke-Item
Move-Item
New-Item
Remove-Item
Rename-Item
Set-Item
Get-PSProvider