On command-line and in parameter of scripting command
open, you can specify basic session settings using session URL.
In WinSCP .NET assembly, you can use session URL too as an alternative way to provide session options. Use method
To ease assembling the URL, you can have WinSCP generate it for you.
- Advanced Settings
- SSH Host Key Fingerprint
- Special Characters
- Directory or File URL
- Other Uses
<protocol> :// [ <username> [ : <password> ] [ ; <advanced> ] @ ] <host> [ : <port> ] /
The only mandatory part is
host. The host can either be a host name (such as
example.com), an IPv4 address (such as
127.0.0.1) or an IPv6 address surrounded by square brackets (such as
You should also always explicitly specify a protocol (
s3, for FTP over implicit TLS/SSL use
ftps, for FTP over explicit TLS/SSL use
ftpes, for WebDAV use
http, for WebDAV over TLS/SSL use
https).1 For all protocols WinSCP-specific alternative is supported, with
Most URL’s will include also
port needs to be specified only, when it differs from the default port for the protocol (22 for
scp, 21 for
ftpes, 990 for implicit
ftps, 80 for
http and 443 for
A session URL can optionally set any advanced session settings using a syntax based on raw site settings.
Providing advanced settings in the session URL is mainly useful, if you need to provide all session settings using URL only, such as using a hyperlink on a web page; or when you want to serialize all session settings into a single “connection string”, such as when passing the current setting settings to a WinSCP extension.
A syntax to serialize raw site settings is
;x-name1=value1;x-name2=value2 (inserted after username and password).
For example to use an HTTP proxy server
proxy, use the following URL:
To have WinSCP generate a session URL with the advanced settings, check Advanced settings on Generate session URL/code dialog. To serialize all session settings for a WinSCP extension, use
SSH Host Key Fingerprint
There’s a special syntax to include an expected SSH host key fingerprint in SFTP/SCP URL among advanced site settings:
For security reasons, fingerprint provided in session URL does not override any fingerprint already cached on the machine. This for instance differs from behavior, when fingerprint is provided using
-hostkey switch of
open command in scripting.
Format of the fingerprint for URL2 somewhat differs from format used in other WinSCP features (
-hostkey switch of
open command in scripting for instance). To convert WinSCP fingerprint format to URL format:
- Drop bit count part (the number after
ssh-dss, etc., typically
- Replace the remaining space with a dash sign (
- Pluses (
+) and slashes (
/) in SHA-256 hash need to be encoded or replaced with dashes (
-) and underscores (
For example WinSCP fingerprint
ssh-rsa 2048 2EP3avJqmpRtSRaUIqwrzavm15vssrhHxJWh9mBaz8M converts to
Special characters (like
@ in username, see example below) have to be encoded using
%XX syntax, where
XX is hexadecimal UTF-8 code.4
Common special characters are:
Note that when specifying session URL on command-line, you cannot use characters that have special meaning on Windows command-line, just as with any other command-line argument. Such characters include
< (less-than sign),
> (greater-than sign),
" (double-quote). To escape these characters, you can wrap whole session URL to double-quotes (
") or encode the characters as shown above.
Further, in Windows batch files,
% (percent sign) needs to be doubled to be used correctly, even when the sign is itself used to encode other special characters. For example, to use
@ in a username, specify
%%40. Other programming and scripting languages have other special characters that need to be escaped using a construct of the respective language (for example
$ in PowerShell has to be escaped as
You can have WinSCP generate correct URL for all kinds of uses (command-line, script or batch file).
To avoid having to URL-encode the credentials, particularly when sourcing them from a variable, you can use
-password switches of the
open command or WinSCP commandline.
sftp://martin:email@example.com/ sftp://firstname.lastname@example.org:2222/ sftp://martin%40example.com:4pRteemail@example.com/ ftp://127.0.0.1:2121/ ftp://[2001:db8:85a3:8d3:1319:8a2e:370:7348]:2121/ sftp://martin;fingerprint=ssh-rsa-2EP3avJqmpRtSRaUIqwrzavm15vssrhHxJWh9mBaz8Mfirstname.lastname@example.org/ http://email@example.com/dav/
Directory or File URL
A URL specified on command-line can include an initial remote path (the path has to end with a slash):
You can also include a file path into the URL:
By default, it will initiate the file download. When combined with
/browse switch, the file will instead be selected in a file panel.
You can also paste the session URL on Login dialog or main window or even Windows File Explorer or web browser (if WinSCP is registered to handle file transfer protocol URL addresses). You can use the session URL as a way to transfer site settings.
You can use custom command patterns
!S to pass a session URL to other processes.
- Protocol is
sftpby default, but the default can be changed.Back
- Fingerprint format for URL is based on draft-ietf-secsh-scp-sftp-ssh-uri.Back
- In case you are still using MD5 fingerprints, replace all colons (
:) with a dash sign (
-) too. Though you should switch to SHA-256 fingerprints.Back
- For multi-byte codes, use
%before every byte, for instance to represent pound-sign