Copying to Another Computer

A shared folder has a network address, a UNC path such as \\back-office\reports, that Test-Path, Get-ChildItem and Copy-Item use like any other path, and where there's no share, Copy-Item -ToSession and -FromSession copy a file through a remoting session made with New-PSSession and closed with Remove-PSSession.

Journeyman · PowerShell · Operating System · Updated

After this lesson you can

  • Read and use a UNC path such as \\back-office\reports with Test-Path, Get-ChildItem and Copy-Item
  • Copy a file to or from another computer through a session with New-PSSession, Copy-Item -ToSession or -FromSession, and Remove-PSSession

Key takeaways

  • A shared folder's address is a UNC path: two backslashes, the computer's name, then the share's name, such as \back-office\reports.
  • Test-Path, Get-ChildItem and Copy-Item work on a UNC path like any other path. Test-Path first, so a script can say plainly when the share can't be reached.
  • With no shared folder, open a session with New-PSSession, copy with Copy-Item -ToSession (there) or -FromSession (back), and close it with Remove-PSSession.
  • Through a session, the path on the far side is a path on that computer, such as C:\Reports, not on yours.

Every Friday the front-desk PC makes the office's weekly report, and the owner reads it at the back-office PC. Today someone emails it across, or carries it on a USB stick, and on the Friday they're out sick, nobody does. Copying a file to another computer is one Copy-Item away, once you know how to write where the other computer is. There are two ways: through a shared folder, or through a remoting session.

This lesson uses a practice folder with the weekly report in it:

New-Item -ItemType Directory -Force -Path "$HOME\terminal-practice\office" | Out-Null
Set-Content -Path "$HOME\terminal-practice\office\weekly-report.txt" -Value 'Weekly report: 14 orders, 2 returns'
Set-Location "$HOME\terminal-practice\office"

A shared folder's address: UNC paths

A shared folder is like the mail tray on the back-office desk that anyone in the office may drop papers into. On Windows, someone right-clicks a folder, chooses to share it with people on the network, and gives the share a name, such as reports. Its address is a UNC path (Universal Naming Convention):

\\back-office\reports\weekly-report.txt

Read it from the left: two backslashes (read "backslash backslash") say "another computer"; then the computer's name, back-office; then the share's name, reports; then folders and files inside it, as on any drive. File Explorer goes to the same place if you type it into its address bar.

A UNC path is a path like any other, so the file commands you know take it as it is. Before copying, look:

Test-Path -Path '\\localhost\office-share'

False

Your own PC is localhost, and it has no share called office-share, so the answer is False. Get-ChildItem -Path '\\localhost\office-share' says the same thing in red: Cannot find path '\localhost\office-share' because it does not exist. On a real network, that same message means one of three things: the PC is off, the share's name is wrong, or your account isn't allowed in.

Copy to a share, safely

When the share is there, copying to it is the Copy-Item you know, with the UNC path as the destination. (Not run here: there's no back-office PC.)

Copy-Item -Path .\weekly-report.txt -Destination '\\back-office\reports\'

In a script that runs every Friday, check first, so a missing share gives a plain message instead of a wall of red:

$share = '\\localhost\office-share'
if (Test-Path -Path $share) {
    Copy-Item -Path .\weekly-report.txt -Destination $share
} else {
    Write-Warning "Can't reach $share. Is that PC on, and is the folder shared?"
}

WARNING: Can't reach \\localhost\office-share. Is that PC on, and is the folder shared?

A share you use every day can get a drive name of its own: New-PSDrive -Name Reports -PSProvider FileSystem -Root '\\back-office\reports' lets you write Reports:\weekly-report.txt until you close the window.

No share? Copy through a session

Sometimes there's no shared folder, and nobody wants one: the owner keeps the reports in C:\Reports on back-office, shared with no one. If remoting is on there (PowerShell Remoting: Invoke-Command and Enter-PSSession), copy through a session, a connection to the other computer that stays open so several commands can use it. New-PSSession opens it, and you keep it in a variable:

$session = New-PSSession -ComputerName back-office
Copy-Item -Path .\weekly-report.txt -Destination 'C:\Reports\' -ToSession $session
Copy-Item -Path 'C:\Reports\printer-log.txt' -Destination . -FromSession $session
Remove-PSSession -Session $session

Line by line: open a session to back-office; copy the report to it; copy a log from it into the folder you're in (.); close the session. The path on the far side is a path on that computer, so C:\Reports\ means back-office's C: drive, not yours. Folders need -Recurse, as always. Close the session when you're done, because each one keeps a PowerShell running on the other PC.

The same session works for Invoke-Command -Session $session and Enter-PSSession -Session $session, so a script can copy a file over and then run it there, with one connection. (These aren't run here, since remoting is off on this PC.)

Which way?

  • A shared folder suits files that people share every day: anyone with permission reaches it from File Explorer or PowerShell, and the share decides who may read or change it.
  • A session suits an administrator's one-off job on a PC with no share, and it needs remoting turned on there.

On a Mac or Linux, -ToSession and -FromSession work the same with a session opened over SSH (New-PSSession -HostName), but UNC paths are for Windows: a Mac opens a share from Finder (Go, then Connect to Server, smb://back-office/reports), and it appears as a folder under /Volumes. Windows PowerShell 5.1 has -ToSession and UNC paths too.

Check yourself

2 questions to try on the lesson page.

So what

The other computer is one path away: \\back-office\reports when there's a share, -ToSession when there isn't, and a Test-Path first so a missing PC gets a plain message.

Key terms

Cheat sheets

Related