If you’re on Windows and need to securely transfer files to and from an SSH host, the Windows tool, WinSCP, may be a great option. WinSCP is a Windows open-source tool that allows you to manage files and directories on remote hosts via SFTP, FTP, AWS S3, and SCP.
Not a reader? Watch this related video tutorial!If WinSCP sounds like an interesting tool, look no further than this ATA Ultimate Guide! In this guide, you will learn how to set up WinSCP and learn all the ways WinSCP helps you transfer files to/from remote hosts.
Let’s get going!
Prerequisites
If you’d like to follow along, side by side, with the demos in this guide, be sure you have the following:
- A Windows XP+ PC – This tutorial will use Windows 10 Enterprise.
- A remote SSH host – This tutorial will use an Ubuntu 18.04.5 LTS machine.
- Putty – If you’d like to learn how to open WinSCP sessions in Putty.
Installing WinSCP
Before you can begin wielding files and directories like a pro with WinSCP, you must first download and install it. Let’s get that done.
Open your favorite web browser, navigate to the WinSCP official download page and download the latest version of WinSCP. This tutorial will be using v5.17.10.
The default WinSCP package will be in English but you can also download other translation packages.
Once downloaded, run the installer and step through the prompts accepting all of the defaults. On the Initial User Settings screen, the tutorial will be using the Commander style of interface. This interface has more features than the trimmed down Explorer interface.
Choosing an Interface
WinSCP has two user interfaces called Commander and Explorer. These interfaces allow you to work with WinSCP via the typical WinSCP (Commander style) or make WinSCP resemble Windows File Explorer.
The biggest difference in the two interfaces is how WinSCP displays file structures. You can see the differences below.
You can change interfaces any time you’d like. To change them:
1. In WinSCP, click on the Options menu and select Preferences.
2. Click on Interface under the Environment category. Here you can see where to select either interface. After you choose an interface, click OK.
3. Close WinSCP and open it again. After you run it again you will notice that WinSCP has changed to the expected interface.
This tutorial will be using the default Commander interface.
Connecting to a Remote Host
You could work with local directories and files all day in WinSCP but that’s not quite the point. You’re using WinSCP to manage remote files! Let’s now dive into how to connect to remote machines!
In WinSCP, there are various ways to connect (and save connections) to remote hosts. To start off, let’s first focus on performing a simple, one-off connection. To do that, click the Session menu. You’ll see a new Login window appear, as shown below.
This window is where you can quickly connect to remote hosts or save connections to hosts known as sites which you’ll learn about later.
If you don’t have any sites created, the window will default to the New Site option in the left-hand window. At this time, you don’t need to worry about sites.
To connect to a remote host, WinSCP requires a few parameters:
- File protocol – The method to connect to the remote host. WinSCP supports five different protocols to connect to remote hosts.
- SFTP or SSH File Transfer Protocol is a network protocol that allows you to transfer files and manage all file activities over a secure network. It is the slowest in general as it encrypts all the data and waits for packet transfer and confirmations.
- FTP or File Transfer Protocol is a protocol is similar to SFTP, but with this protocol, you have an option to either authenticate yourself, which is secured with SSL/TLS protocol, or you can connect anonymously if the remote server allows. FTP is faster than the SFTP protocol.
- SCP or Secure Copy Protocol is a protocol that copies the files from one machine to a remote machine securely over SSH. SCP is supported on Unix-like platforms only. The speed of copying the files is faster than SFTP.
- WebDAV or Web Distributed Authoring and Versioning is an extension of the Hypertext Transfer Protocol (HTTP) that allows the users to edit and manage documents and files stored on web servers.
- S3 or Amazon Simple Storage Service is a web service provided by Amazon Web Services. It is a storage service that works on various protocols such as REST, SOAP, and many more, but WinSCP uses REST to work with the S3 service.
- Host name – The remote host’s hostname or IP address.
- Port number – The TCP port number the remote host’s File protocol is listening on. Most SSH implementations listen on the default TCP port 22.
- User name – The username to connect to the remote host
- Password – The password for the username to connect with.
When you’ve completed filling in all of the connection information, click on the Login button to connect to the remote host.
When connected, WinSCP will then display the remote host’s home directory on the right side and show the current session’s connected username and host, as shown below.
At this point, you can now begin navigating directories for both the local and remote sessions and managing files between sessions.
Navigating Directories
When WinSCP creates a remote session with a host, it will drop you into the user account you connected with’s home directory. Chances are, this directory isn’t the directory you’d like to be in. When that happens, you must start navigating around to find the directory and/or files you’d like to work with.
Opening Parent Directories
Just like Windows Explorer, WinSCP represents directories as folders in both the local and remote session panes. You can click around and drill into directories like you’re used to. But, unlike Windows Explorer, WinSCP doesn’t have an up arrow allowing you to navigate into parent directories.
A file system stores directories in a hierarchical fashion with parent and child directories. If you’re in a child directory, double-click on the two dots (..), as shown below. You’ll see that WinSCP changes the directory to the current directory’s parent.
Opening Specific Directory Paths
Although you can navigate file systems with WinSCP to find directories, you can also open specific directory paths if you know them ahead of time.
If you know a specific directory path you’d like to open, click on the Local menu —> Go To —> Open Directory/Bookmark, as shown below. WinSCP will then open a window titled Open directory which prompts you with a Browse button allowing you to type in a path or browse to one.
You’ll notice a Local and Remote option in the menu bar. These two options contain similar actions. The Local menu performs actions on the local computer and the Remote menu performs actions on the remote computer.
Bookmarking Directories
If you have certain directories you access often, WinSCP allows you to bookmark directories. Bookmarking directories create a common list of directories you can easily come back to later.
Creating Directory Bookmarks
To bookmark directories in WinSCP:
1. Click on the directory you’d like to bookmark in the directory pane.
2. Click on the Local menu —> Add Path to Bookmarks. This action will bring up a confirmation box, as you can see below.
Notice the Add to shared bookmarks checkbox. WinSCP has session and shared bookmarks. Session bookmarks are only applicable to the current session. When you disconnect from the session, your bookmarks disappear. Shared bookmarks, on the other hand, remain saved and you must manually remove them.
3. Click OK to confirm the bookmark.
Opening Bookmarked Directories
Once you have one or more bookmarks created, you can then quickly navigate to those bookmarked directories. To do so:
1. Navigate to the Local menu —> Go To —> Open Directory/Bookmark.
2. Select the bookmarked directory, as shown below.
In the below screenshot, you’ll see the entry C:\Users\Public show up in the Shared bookmarks tabs. This bookmark exists here because when saving the bookmark, the Add to Shared bookmarks checkbox was enabled.
3. Click OK to open the bookmark.
Once you click on OK, WinSCP will then take you directly to the directory.
Navigating Files
You’re going to be doing a lot with files in WinSCP so it’s important you know the ropes! Other than clicking around in the filesystem, WinSCP has a few little-known features you may not be aware of.
Finding Files
If you’d like to transfer some files to/from a remote session in a directory with hundreds or thousands of files, you don’t have to click around until you find them. Instead, you can use WinSCP’s filtering capability to narrow down on exactly what you’re looking for.
To filter out all of the files you’re not looking for in the file panes:
1. Click on the Local (or Remote) menus and click on Filter. This action will bring up the Filter dialog box where you can provide a File mask.
2. In the File mask box, provide a file mask based on the required syntax.
3. Click on the Edit button and you will see a graphical way to create a file mask filter.
4. Click OK and you’ll see the file pane only shows the files that match your file mask.
Sorting Files
In WinSCP, you can sort files in either the local or remote file pane based on various criteria like name, extension, date modified and more.
To sort files, click on the Local (or Remote) menu —> Sort and choose the attribute you’d like to sort files on.
Showing Hidden Files
Are you not seeing all of the files you know to exist on the local or remote computer? They might be hidden. To show hidden files in WinSCP:
Click on Options —> Preferences. Inside of the Preferences window, click on the Panels section and select Show hidden files (Ctrl-Alt-H).
WinSCP has several keyboard shortcuts to prevent clicking around.
Once you tell WinSCP to show hidden files, it will then allow you to manage those files as you’d expect.
Selecting Files
Before you can transfer files, you must first select which ones you’d like to transfer. If you’re simply copying a few files, simply navigating to the directories you need, clicking a file, or holding Ctrl or Shift and selecting multiple files will work.
Sometimes, you’ll have many different files matching various criteria to transfer. In that case, take a look at the Mark menu. In WinSCP, “marking” allows you to create filters for files in a specific directory which will then select them all.
For example, perhaps you have a large directory of files opened and would like to only transfer the files with a file extension of ps1. To do that:
1. Click on the Mark menu and click Select Files…, as shown below.
2. Next, specify the file mask you’d like for each file to match.
You’ll notice the the Select Files and Filter feature both use the same method to specify a file mask.
If you need to apply more advanced filters, you could click on the Edit button which brings up other options to apply to your filter.
Click OK to confirm the selection filter and you’ll see that the current directory contains all of the subdirectories and filters that match the selection filter are selected.
Transferring Files
So you’ve now customized WinSCP to your liking, connected to a remote session, and know how to navigate around the local and remote filesystems. It’s time to start actually doing something with WinSCP; transferring some files!
Within WinSCP, you have many different ways you can transfer (and even sync) local and remote files. Let’s now cover each method from easiest to most advanced.
Dragging and Dropping
Whenever you’re connected to a remote host, one of the easiest ways to transfer files is by dragging and dropping one or more files to and from local and remote windows.
To copy files via drag and drop, first, navigate to the local and remote directories you’d like to transfer files to/from and click and drag one or directories or files across.
You can also use the keyboard to select items with the arrow keys to switch between items, using the spacebar or the Insert key to select them.
Copying and Pasting
If dragging and dropping isn’t your thing, you can also copy and paste files to/from remote hosts. To do so, select one or more files, right click them and select Copy.
In the other window, navigate to the directory you’d like to copy the files you’ve just selected, right click in the window, and choose Paste.
Invoking an Advanced Transfer
Dragging and dropping or copying and pasting files does transfer files with WinSCP but your options are limited. By default, for example, WinSCP uses the binary transfer mode. Perhaps you’d rather use text mode? You can set many different options to perform a file transfer in WinSCP.
To invoke an advanced transfer, select the files you’d like to transfer and hit the F5 key. Hitting this key will bring up an Upload window to select various transfer options.
At this point, you have a few options. You could either perform a standard transfer by clicking OK or you could change the file mask here to only transfer certain files.
If you’d click on the Transfer Settings button though, you’d have a whole lot more options this tutorial will not cover. In the Transfer Settings window, you can change the transfer mode, set permissions on files once uploaded, preserve the local timestamp, and more.
Background Transfers and the Transfer Queue
If you’re transferring a file here and there, typically, you’ll be transferring files via WinSCP in the foreground. You’ll transfer the files, watch the progress and move on. But, if you have many different files that may take many minutes or even hours or have an automation routine, you can also transfer files in the background and use the WinSCP queue.
Using background transfers, you can speed up file transfers by transferring in parallel or simply free up your WinSCP console to do other things while files are transferring.
To transfer files in the background, invoke an advanced transfer as described in the previous section. In the Transfer Settings dialog box, you’ll see an option labeled Transfer in the background (add to transfer queue).
By selecting Transfer in background option when performing a transfer, WinSCP will immediately add the transfer to the transfer queue, as shown below. The transfer queue is where WinSCP tracks all background transfers.
Once a transfer is in the transfer queue, you can perform other activities in WinSCP includes initiating another transfer! The transfer queue is a great way to perform various transfers at once and to queue them all up instead of waiting for each transfer to complete.
For each background transfer, WinSCP opens a separate connection to the server using the same session options you defined when creating the session. These new connections are kept in the background and reused for future transfers.
By default, the transfer queue will only attempt to perform two transfers at once. You can change this behavior by opening the Preferences menu and changing the Maximal number of transfers at the same time under the Background section, as shown below.
In the Background transfers Preferences menu, you can change the behavior of the transfer queue.
Managing WinSCP Sites
Even though WinSCP lets you connect to remote hosts quickly, by default, it won’t save those connections. Chances are, you’ve got many different hosts in your environment and it’s going to get old remembering the hostname and credentials.
Let’s say you have a remote host with SSH enabled that you connect to often. You’d like to save that connection so you can browse to that host and automatically connect. To create saved connections or what WinSCP refers to as sites, you can save connections to remote hosts so that you can simply browse to a site and connect.
Creating WinSCP Sites
To create a WinSCP site and save your session for later use:
1. Click the Session menu as mentioned in the Connecting to a Remote Host section and provide all of the necessary connection information.
2. Click on the Save button.
3. Next, provide a Site name for the saved connection and an optional folder and click OK to confirm.
If you just have a handful of connections you’d like to save, you don’t need a folder but if you’re using WinSCP to connect to dozens or even hundreds of different hosts, categorizing connections into folders is a great way to find those connections later.
Now, In the Login window, you’ll see your new site. This time, instead of the session properties being available to edit, they’re all greyed out. The properties are now saved in a site.
4. Finally, click on Login to test the site’s connection. After you click on Login, the connection to a new site begins.
5. Select Yes to add the server host keys to your system cache so that WinSCP can trust the remote host. If you trust the remote host’s key details, click the Yes button.
You don’t have to save the server host’s keys. If you click No, you’ll still be able to connect to the remote host but you will receive this prompt every time.
Once you’ve created at least one site, you now find them by clicking on the Session menu —> Sites and clicking on the site you’d like to connect to, as shown below.
Editing, Renaming and Removing WinSCP Sites
Once you have a site created, you can then modify it however you’d like. Maybe you need to edit properties of an existing site like changing the hostname or username perhaps, you can do that too in WinSCP.
1. Click on the Session menu item which will bring up the Login window again. You will see all of the saved sites in the Login window.
You can alternatively bring up the Login window/Site Manager by clicking on the Session menu —> Sites —> Site Manager.
2. Find the site you’d like to edit, right-click on the site and click on Edit, as shown below. The previously greyed-out options will now be available to edit.
To rename or delete a site, click on the Delete or Rename menu item. You can even create copies of sites that perhaps share the same username by clicking on Clone to New Site.
3. When you’ve edited any needed properties, click on the Save button, as shown below.
You’ll see an Advanced button in the Site Manager. WinSCP stores sites in files. If you need to modify settings of a site in the files themselves, here you can edit the raw settings and modify advanced settings you might not need too often.
Backing Up and Restoring All Sites
Perhaps you’ve created dozens of sites and get a new computer. Now what? WinSCP doesn’t have a cloud service it syncs to. You must manually transfer over those sites. To do that, WinSCP has a concept called configurations that allow you to backup and restore all of your sites.
To export all saved sites:
Open the Site Manager and click on the Tools button. Click on Export/Backup Configuration which will prompt you to save all of your sites in an INI file in your location of choice.
To import a saved configuration, click on Import/Restore Configuration. Importing a configuration will overwrite all existing sessions!
Importing Sites from Other Tools
If you’re using the popular Putty SSH client and already have saved sessions in there, there’s no reason to reinvent the wheel. You can import all of those sessions directly into WinSCP.
To do import sites from other tools like Putty:
1. Open the Session Manager.
2. Right click anywhere in the left site menu and click on Import Sites. WinSCP will bring up the Import sites window showing you all of the supported sources to import sites from such as Putty, FileZilla, and known_hosts.
3. Select a source to import from. WinSCP should then provide you with each site it’s capable of importing in the box below.
Select each session you’d like to import or click the Un/check all button and click on OK to import the sessions.
Session Logging
If you need to go back to a command issued in a remote session, you’re going to need some way to save the history. WinSCP provides a session logging feature that does just that. Open the Preferences menu item and click on the Logging option, you’ll see a way to enable session logging.
Don’t worry. Passwords are never recorded in any log unless you choose the Log passwords and other sensitive information checkbox.
To enable session logging, check the Enable session logging on level checkbox and provide a logging level.
Session Logging Options
In the session log, WinSCP logs events in an instructured way that varies by the protocol the session is using. The session log is typically good for troubleshooting purposes.
You have a few different levels of logging you can define for the session log.
- Reduced – The least granular logging level.
- Normal – This logging level is typically good enough for most troubleshooting or auditing and is the default.
- Debug 1/Debug 2 to get extremely granular.
The Log Path is where WinSCP will save the log file. Here you can specify dynamic criteria to have WinSCP save the log files according to date/time attributes and more.
You can use a combination of patterns to create the desired log file name such as:
- Year –
!Y - Month –
!M - Day –
!D - Time –
!T - Hostname –
!@ - Session Name –
!S - Process ID –
!P - Exclamation Mark –
!!
Limit log sizes by defining the maximum size a log file can grow by enabling the Rotate log files after reaching checkbox. In this dropdown, you can use K, M, and G to represent bytes. If a log file grows too large, WinSCP will create a copy with an extension .1, .2, etc.
If you’re already in a session and enable logging, logging will start when you enable it. WinSCP will not record all previous session history in the log file.
The XML Log
You’ll configure what to record and how to record it in the Session Log section. The session log records logs in an unstructured text file. But, if you need a more structured approach for future parsing, you should tick Enable XML logging to file.
By enabling XML logging, WinSCP will generate a structured XML file. This format includes less information than the session log but can be used for scripting purposes.
Managing Workspaces
Perhaps, you routinely work with a set of sites you have open all day. You typically need to access these hosts in some way. Rather than opening up each site every day, you can save them all in a workspace to save all connected sites as one.
Saving a Workspace
Perhaps you have dozens of sites open and want to immediately come back to them at one time. You need to create/save a workspace. To do that, click on the Session menu and choose Save Workspace. WinSCP will then prompt you for a place to save the workspace file.
In the Save workspace as dialog box, provide a name and select whatever or you not you’d like to save any passwords.
You’ll also see a Create desktop shortcut option. If you select this option, WinSCP will create a desktop shortcut with the following target. This target will open a workspace called My Workspace. This desktop shortcut is handy because, without it, you’ll have to open the workspace with the Session Manager, as explained in the next section.
C:\Program Files (x86)\WinSCP\WinSCP.exe "My%20Workspace" /DesktopYou’ll also see an Enable automatic saving of this workspace option. This option is handy because you won’t’ have to manually save your workspace as demonstrated above.
Opening/Restoring a Workspace
Once you have saved a workspace on your computer somewhere, you need to open it somehow. To open/restore a workspace:
Open Site Manager, find the workspace in the left pane, right-click on the workspace, and select Login.
The workspace saved when WinSCP was closed the last time is automatically selected when the Login dialog opens
Running SSH Commands on Remote Hosts
Using features like the built-in command-line box, custom commands, and even Putty, you can quickly run various short commands on a connected host.
The WinSCP Command Line
If you need to run a simple SSH command without having to open a separate SSH client, you can do so by using the WinSCP command line feature. To access the feature, click on the Options menu and select Command Line, as shown below. You’ll see a Command box appear at the bottom.
Once you have the Command box open, type in any terminal command you wish and WinSCP will execute it on the remote host. For example, type ifconfig , as shown below, to discover IP address information on the remote host.
Do not run commands that require user input. The WinSCP command line doesn’t support interactive commands.
Custom Commands
Let’s say you find yourself running a particular command over and over on a remote host or maybe you’d like to run a particular command against all files in the remote file pane. If so, WinSCP’s custom commands feature is for you.
Custom commands are pre-configured commands that can contain variables representing environmental attributes like the host you’re connected to, the user you’re connected with, and more. Custom commands templatize common actions.
For example, running a custom command such as cat "!", runs the cat command on every selected file in the remote panel. Or, you can just have a complex SSH command to save and run later.
To set up and run custom commands, click on the Commands menu and then on Static Custom Commands. This menu is where you will see how to enter ad-hoc custom commands or even save some of your own.
To demonstrate, click on Enter. The Custom Command window will appear.
In the Custom Command window, type echo !S to see how WinSCP translates the !S placeholder with the session URL and click OK.
You can find all placeholders on the WinSCP Custom Commands documentation page.
Notice that since the Show results in terminal option was selected, WinSCP brought up the same Console window as used with the command line feature. Below you can see that !S was translated to sftp://automate:automate which is the session URL.
Using Putty
Once you’ve created a session in WinSCP, you don’t have to use WinSCP to do further tasks. You can actually pass that session to the popular Putty SSH client.
If you’re currently in a WinSCP session, open a WinSCP session in Putty by clicking on the Commands menu and click on Open in Putty. You’ll see that Putty opens and connects to the remote host you’re connected to in WinSCP.
By default, Putty will prompt for a password unless you add access key id and secret key for the particular machine.
Cleaning Up
WinSCP stores several types of data on your system on the file system and in the registry. If you’re on a shared computer, for example, you might want to clean all of this up. To do so:
1. Open the Site Manager.
2. Click on the Tools button.
3. Click on Clean Up. You’ll then see a Cleanup application data box, as shown below.
4. Select on each item (typically General configuration which is all workspace and site-related information stored in the registry) and Random seed file which contains randomly generated data on WinSCP startup to seed its encryption random number generator.
Keeping up to Date and Getting Help
Finally, it’s important to keep WinSCP up to date for the latest bug fixes and features. If you think you’re version is out of date, click on the Help menu and click Check for Updates. WinSCP will check for a new version and will prompt you to install a new version if one exists.
The Help menu is also a great place to find WinSCP documentation, a place to donate to the open-source project if you wish and more.
Conclusion
WinSCP is a handy, free tool to help you transfer files and also run remote commands on computers. Through its built-in sites, various ways to select and transfer files, you can’t beat it for the price.
Now that you’re a WinSCP guru, how do you plan to use it?
