This is an old revision of the document!

Protocol URL Addresses

WinSCP can be registered to handle file transfer protocol URL addresses. See supported URL format.

Advertisement

Registering to Handle URL Addresses

To register WinSCP to handle the URL addresses use installer or go to Preferences dialog.

If current user’s permissions allow, WinSCP register itself for all users. Otherwise it registers for current user only.

Windows Vista and Newer

On Windows 11, Windows 10, Windows 8, Windows 7, and Windows Vista, WinSCP registers to list of applications that handle sftp://, ftp://, ftps://, ftpes://, scp://, ssh://, dav://, davs:// and s3:// protocol URL addresses. If WinSCP is the first application to support some of these protocols (most often sftp://, scp://, ssh://, dav://, davs:// and s3://, usually also ftps:// and ftpes://), it becomes a default application for these.

If you want to change the registration (for instance to make WinSCP default application even for ftp:// URL addresses):

  • On Integration page of Preferences dialog go to Register to handle URL addresses > Make WinSCP default handler;1
  • Windows 11 and Windows 10:
    • Windows 11: The Settings app opens with Default Apps page. Locate and select WinSCP in the application list.
    • Windows 10: The Settings app opens with Default Apps page. At the bottom of the page, click Set defaults by app link. Locate and select WinSCP in the application list. After selecting WinSCP, click the Manage button.
    • One by one locate the protocols that you want to associate with WinSCP and select Choose a default. In the popup menu, select WinSCP.
    • In case you have both classic and Microsoft Store installation, they cannot be distinguished in the application list. But at that stage, it does not matter which one you select. Later in the popup menu, when associating a protocol, select “WinSCP”, if you want to use the Microsoft Store installation, or "WinSCP: SFTP, FTP, WebDAV, S3 and SCP client", if you want to use the classic installation.
  • Windows 8, Windows 7 and Windows Vista:
    • The Set Program Associations Control Panel applet for WinSCP opens;
    • Choose the protocols you want WinSCP to be the default application for.

Advertisement

WinSCP never registers to handle WebDAV http:// URL addresses not to conflict with web browser registration. Though, it registers dav://, davs:// and WinSCP-specific WebDAV URL addresses.

Windows XP

On Windows XP, WinSCP registers to handle sftp://, scp://, dav://, davs:// and s3:// protocol URL addresses, overriding previous registration, if any.

To change the registration:

  • Go to Control Panel > Folder Options > File Types;
  • Search a list for File types “URL: SFTP Protocol”, “URL: SCP Protocol”, etc;
  • Click Advanced button;
  • Select “open” action;
  • Click Edit button.

WinSCP-specific URL protocols

In addition to registering to generic URL protocols, WinSCP registers for application-specific URL protocols with winscp- prefix, i.e. winscp-sftp://, winscp-ftp://, etc.

Using WinSCP-specific URL protocols is reasonable, when using WinSCP-specific extension for URL syntax, particularly the save extension.

Handling URL Addresses

If a handled URL does not include path part, WinSCP simply opens a session specified by the URL.

If path part is included and it ends with slash (/), WinSCP starts with the path as initial remote directory. If the path part does not end with slash, the file (or directory) specified by it is downloaded.

For ssh:// URL, WinSCP opens the session specified by the URL in PuTTY.

If the URL (without the protocol prefix) or its part matches a name of a stored site, WinSCP will use setting from that site. That can be used for example to specify default credentials or a proxy server for a hostname.

Save Extension

To make WinSCP save session settings provided by URL to a site instead of opening a session, add ;save after a path part of the URL (if there is no path part, terminate the URL with / before adding the ;save extension).

For SFTP/SCP URL this should be combined with including SSH host key fingerprint in the URL. As this is WinSCP-specific extension, and also to avoid conflicts with other applications, like web browsers, consider using WinSCP-specific URL protocols.

Example: winscp-sftp://martin:mypassword;fingerprint=ssh-rsa-xxxxxxxxxxx...@example.com/;save

Generating URL

You can have WinSCP generate URL using:

  • Tabs > Generate Session URL/Code command on the main window to generate session URL for current session (preferred as it guarantees that SSH host key fingerprint is included in the URL).
  • Manage > Generate Session URL/Code command on Login dialog to generate session URL for selected site.
  • Files > File Names > Generate File URL command on the main window to generate file URL for files selected in remote file panel.

Advertisement

Injecting URL to a Page

You can use a user script to inject SFTP or FTP URL to a page (such an Amazon EC2 management console).

  1. Alternatively: On Windows 11 and Windows 10, go to Settings > Apps > Default Apps. On Windows 7 and older: go to Control Panel > Programs > Default Programs > Set your default programs; Locate WinSCP in the list; Click Choose defaults for this program command link.Back

Last modified: by martin