1. The pysftp module is a simple interface to SFTP. The module offers high level abstractions and task based routines to handle the SFTP needs. So we install the module into our python environment with the below command. Pip install pysftp Example. In the below example we login to a remote server using sftp and then get and put some file in that.
  2. With pysftp.Connection(host, username, password, cnopts=cnopts) as sftp: An easy way to retrieve the host key in this format is using OpenSSH ssh-keyscan: $ ssh-keyscan

Previous Contents Next

PSFTP, the PuTTY SFTP client, is a tool for transferring files securely between computers using an SSH connection.

PSFTP differs from PSCP in the following ways:

  • PSCP should work on virtually every SSH server. PSFTP uses the new SFTP protocol, which is a feature of SSH 2 only. (PSCP will also use this protocol if it can, but there is an SSH 1 equivalent it can fall back to if it cannot.)
  • PSFTP allows you to run an interactive file transfer session, much like the Windows ftp program. You can list the contents of directories, browse around the file system, issue multiple get and put commands, and eventually log out. By contrast, PSCP is designed to do a single file transfer operation and immediately terminate.

Section 6.1: Starting PSFTP

The usual way to start PSFTP is from a command prompt, much like PSCP. To do this, it will need either to be on your PATH or in your current directory. To add the directory containing PSFTP to your PATH environment variable, type into the console window:


If you enjoy automating things in python, you are going to need to know how to upload and download files from a server. SFTP (Secure Shell File Transfer Protocol) has replaced the less secure FTP. This pysftp method is an abstraction that recursively copies files and directories from the remote to a local path. # copy all files AND directories under public to a local path sftp.getr('public','local-backup', preservemtime=True) 4.1.6 pysftp.Connection.put.

Unlike PSCP, however, PSFTP has no complex command-line syntax; you just specify a host name and perhaps a user name:

or perhaps

Alternatively, if you just type psftp on its own (or double-click the PSFTP icon in the Windows GUI), you will see the PSFTP prompt, and a message telling you PSFTP has not connected to any server:

At this point you can type open or open [email protected] to start a session.

The following sections describe PSFTP's command-line options.

6.1.1 -l: specify a user name

The -l option is an alternative way to specify the user name to log in as, on the command line. Instead of typing psftp [email protected], you can also type psftp host -l user.

This option does not work in the open command once PSFTP has started.

6.1.2 -P: specify a port number

If the host you specify is a saved session, PSFTP uses any port number specified in that saved session. If not, PSFTP uses the default SSH port, 22. The -P option allows you specify the port number to connect to for PSFTP's SSH connection.

6.1.3 -v: show verbose messages

The -v option to PSFTP makes it print verbose information about the establishing of the SSH connection. The information displayed is equivalent to what is shown in the PuTTY Event Log (section

This information may be useful for debugging problems with PSFTP.

6.1.4 -pw: specify a password

If a password is required to connect to the host, PSFTP will interactively prompt you for it. However, this may not always be appropriate. If you are running PSFTP as part of some automated job, it will not be possible to enter a password by hand. The -pw option to PSFTP lets you specify the password to use on the command line.

Since specifying passwords in scripts is a bad idea for security reasons, you might want instead to consider using public-key authentication; see section 6.3.

6.1.5 -b: specify a file containing batch commands

In normal operation, PSFTP is an interactive program which displays a command line and accepts commands from the keyboard.

If you need to do automated tasks with PSFTP, you would probably prefer to specify a set of commands in advance and have them executed automatically. The -b option allows you to do this. You use it with a file name containing batch commands. For example, you might create a file called myscript.scr containing lines like this:

and then you could run the script by typing

When you run a batch script in this way, PSFTP will abort the script if any command fails to complete successfully. To change this behaviour, you can use the -be option (section 6.1.7).

6.1.6 -bc: display batch commands as they are run

The -bc option alters what PSFTP displays while processing a batch script. With the -bc option, PSFTP will display prompts and commands just as if the commands had been typed at the keyboard. So instead of seeing this:

you might see this:

6.1.7 -be: continue batch processing on errors

When running a batch file, this option causes PSFTP to continue processing even if a command fails to complete successfully.

You might want this to happen if you wanted to delete a file and didn't care if it was already not present, for example.

6.1.8 -batch: avoid interactive prompts

If you use the -batch option, PSFTP will never give an interactive prompt while establishing the connection. If the server's host key is invalid, for example (see section 2.2), then the connection will simply be abandoned instead of asking you what to do next.

This may help PSFTP's behaviour when it is used in automated scripts: using -batch, if something goes wrong at connection time, the batch job will fail rather than hang.

Section 6.2: Running PSFTP

Once you have started your PSFTP session, you will see a psftp> prompt. You can now type commands to perform file-transfer functions. This section lists all the available commands.

6.2.1 General quoting rules for PSFTP commands

Most PSFTP commands are considered by the PSFTP command interpreter as a sequence of words, separated by spaces. For example, the command ren oldfilename newfilename splits up into three words: ren (the command name), oldfilename (the name of the file to be renamed), and newfilename (the new name to give the file).

Sometimes you will need to specify file names that contain spaces. In order to do this, you can surround the file name with double quotes. This works equally well for local file names and remote file names:

The double quotes themselves will not appear as part of the file names; they are removed by PSFTP and their only effect is to stop the spaces inside them from acting as word separators.

If you need to use a double quote (on some types of remote system, such as Unix, you are allowed to use double quotes in file names), you can do this by doubling it. This works both inside and outside double quotes. For example, this command

will take a file whose current name is 'this' (with a double quote character at the beginning and the end) and rename it to a file whose name is a file with 'quotes' in it.

(The one exception to the PSFTP quoting rules is the ! command, which passes its command line straight to Windows without splitting it up into words at all. See section 6.2.16.)

6.2.2 The open command: start a session

If you started PSFTP by double-clicking in the GUI, or just by typing psftp at the command line, you will need to open a connection to an SFTP server before you can issue any other commands (except help and quit).

To create a connection, type open, or if you need to specify a user name as well you can type open [email protected].

Once you have issued this command, you will not be able to issue it again, even if the command fails (for example, if you mistype the host name or the connection times out). So if the connection is not opened successfully, PSFTP will terminate immediately.

6.2.3 The quit command: end your session

When you have finished your session, type the command quit to terminate PSFTP and return to the command line (or just close the PSFTP console window if you started it from the GUI).

You can also use the bye and exit commands, which have exactly the same effect.

6.2.4 The help command: get quick online help

If you type help, PSFTP will give a short list of the available commands.

If you type help with a command name - for example, help get - then PSFTP will give a short piece of help on that particular command.

6.2.5 The cd and pwd commands: changing the remote working directory

PSFTP maintains a notion of your 'working directory' on the server. This is the default directory that other commands will operate on. For example, if you type get filename.dat then PSFTP will look for filename.dat in your remote working directory on the server.

To change your remote working directory, use the cd command. To display your current remote working directory, type pwd.

6.2.6 The lcd and lpwd commands: changing the local working directory

As well as having a working directory on the remote server, PSFTP also has a working directory on your local machine (just like any other Windows process). This is the default local directory that other commands will operate on. For example, if you type get filename.dat then PSFTP will save the resulting file as filename.dat in your local working directory.

To change your local working directory, use the lcd command. To display your current local working directory, type lpwd.

6.2.7 The get command: fetch a file from the server

To download a file from the server and store it on your local PC, you use the get command.

In its simplest form, you just use this with a file name:

Pysftp List Files

If you want to store the file locally under a different name, specify the local file name after the remote one:

This will fetch the file on the server called myfile.dat, but will save it to your local machine under the name newname.dat.

6.2.8 The put command: send a file to the server

To upload a file to the server from your local PC, you use the put command.

In its simplest form, you just use this with a file name:

If you want to store the file remotely under a different name, specify the remote file name after the local one:

This will send the local file called myfile.dat, but will store it on the server under the name newname.dat.

6.2.9 The reget and reput commands: resuming file transfers

If a file transfer fails half way through, and you end up with half the file stored on your disk, you can resume the file transfer using the reget and reput commands. These work exactly like the get and put commands, but they check for the presence of the half-written destination file and start transferring from where the last attempt left off.

The syntax of reget and reput is exactly the same as the syntax of get and put:

6.2.10 The dir command: list remote files

To list the files in your remote working directory, just type dir.

You can also list the contents of a different directory by typing dir followed by the directory name:

The ls command works exactly the same way as dir.

6.2.11 The chmod command: change permissions on remote files

PSFTP allows you to modify the file permissions on files on the server. You do this using the chmod command, which works very much like the Unix chmod command.

The basic syntax is chmod modes file, where modes represents a modification to the file permissions, and file is the filename to modify. For example:

The modes parameter can be a set of octal digits in the Unix style. (If you don't know what this means, you probably don't want to be using it!) Alternatively, it can be a list of permission modifications, separated by commas. Each modification consists of:

  • The people affected by the modification. This can be u (the owning user), g (members of the owning group), or o (everybody else - 'others'), or some combination of those. It can also be a ('all') to affect everybody at once.
  • A + or - sign, indicating whether permissions are to be added or removed.
  • The actual permissions being added or removed. These can be r (permission to read the file), w (permission to write to the file), and x (permission to execute the file, or in the case of a directory, permission to access files within the directory).

So the above examples would do:

  • The first example: go-rwx removes read, write and execute permissions for members of the owning group and everybody else (so the only permissions left are the ones for the file owner). u+w adds write permission for the file owner.
  • The second example: a+r adds read permission for everybody.

In addition to all this, there are a few extra special cases for Unix systems. On non-Unix systems these are unlikely to be useful:

  • You can specify u+s and u-s to add or remove the Unix set-user-ID bit. This is typically only useful for special purposes; refer to your Unix documentation if you're not sure about it.
  • You can specify g+s and g-s to add or remove the Unix set-group-ID bit. On a file, this works similarly to the set-user-ID bit (see your Unix documentation again); on a directory it ensures that files created in the directory are accessible by members of the group that owns the directory.
  • You can specify +t and -t to add or remove the Unix 'sticky bit'. When applied to a directory, this means that the owner of a file in that directory can delete the file (whereas normally only the owner of the directory would be allowed to).

6.2.12 The del command: delete remote files

To delete a file on the server, type del and then the filename:

The rm command works exactly the same way as del.

6.2.13 The mkdir command: create remote directories

To create a directory on the server, type mkdir and then the directory name:


6.2.14 The rmdir command: remove remote directories

To remove a directory on the server, type rmdir and then the directory name:

Most SFTP servers will probably refuse to remove a directory if the directory has anything in it, so you will need to delete the contents first.

6.2.15 The ren command: rename remote files

To rename a file on the server, type ren, then the current file name, and then the new file name:

The rename and mv commands work exactly the same way as ren.

6.2.16 The ! command: run a local Windows command

You can run local Windows commands using the ! command. This is the only PSFTP command that is not subject to the command quoting rules given in section 6.2.1. If any command line begins with the ! character, then the rest of the line will be passed straight to Windows without further translation.

For example, if you want to move an existing copy of a file out of the way before downloading an updated version, you might type:

using the Windows ren command to rename files on your local PC.

Section 6.3: Using public key authentication with PSFTP

Like PuTTY, PSFTP can authenticate using a public key instead of a password. There are two ways you can do this.

Firstly, PSFTP can use PuTTY saved sessions in place of hostnames. So you might do this:

  • Run PuTTY, and create a PuTTY saved session (see section 4.1.2) which specifies your private key file (see section 4.16.5). You will probably also want to specify a username to log in as (see section 4.12.2).
  • In PSFTP, you can now use the name of the session instead of a hostname: type psftp sessionname, where sessionname is replaced by the name of your saved session.

Secondly, PSFTP will attempt to authenticate using Pageant if Pageant is running (see chapter 9). So you would do this:

  • Ensure Pageant is running, and has your private key stored in it.
  • Specify a user and host name to PSFTP as normal. PSFTP will automatically detect Pageant and try to use the keys within it.

For more general information on public-key authentication, see chapter 8.

Pysftp Install

Previous Contents Next

Comments to [email protected][$Id: blurb.but,v 1.5 2001/12/16 14:56:02 simon Exp $]
[$Id: intro.but,v 1.4 2001/11/25 16:57:45 simon Exp $]
[$Id: gs.but,v 1.6 2001/12/06 20:05:39 simon Exp $]
[$Id: using.but,v 1.5 2001/12/15 12:15:24 simon Exp $]
[$Id: config.but,v 1.24 2001/12/29 17:25:07 simon Exp $]
[$Id: pscp.but,v 1.20 2001/12/31 16:15:19 simon Exp $]
[$Id: psftp.but,v 1.4 2001/12/31 16:15:19 simon Exp $]
[$Id: plink.but,v 1.13 2001/12/31 16:15:19 simon Exp $]
[$Id: pubkey.but,v 1.13 2001/12/14 09:58:07 simon Exp $]
[$Id: pageant.but,v 1.7 2001/12/20 15:27:40 simon Exp $]
[$Id: faq.but,v 1.18 2002/01/14 12:16:58 simon Exp $]
[$Id: feedback.but,v 1.2 2001/12/16 15:14:36 simon Exp $]
[$Id: licence.but,v 1.2 2002/01/08 11:57:32 simon Exp $]Latest version


A friendly face on SFTP

Project description

A simple interface to SFTP. The module offers high level abstractions andtask based routines to handle your SFTP needs. Checkout the Cook Book, in thedocs, to see what pysftp can do for you.


Tested on Python 2.7, 3.2, 3.3, 3.4

  • Project:
  • Download:
  • Documentation:

Change Log

  • 0.2.9 (current, released 2016-07-04)
    • bugfix: correctly implement hostcheck. Now, be default pysftp will verifythe host. See pysftp.CnOpts.hostkeys
    • added pysftp.Connection.remote_server_key - used to retrieve theremote hosts server key.
    • added support for enabling compression, compression (J. Kruth)
    • added .active_compression, to return the active local and remote compression settings as a tuple
    • fixed an unwanted logging side-effect, after you set logging, it would remain, even if you closed the .Connection and couldn’t be changed to something else. Now when Connection closes, any logging handlers are closed and can be changed to something else upon the next .Connection
    • moved log parameter of Connection to the new CnOpts connection options object, deprecated the existing log parameter, will be removed in 0.3.0
    • modified pysftp.Conection.walktree to always use posixpath conventions when walking a remote directory per the latest draft-ietf-secsh-filexfer-13.txt. Issue encountered with windows clients (#60)
    • modified pysftp.reparent to handle mis-matched pathing, i.e. windows -> posix, better (#61)
  • 0.2.8 (released 2014-05-28)
    • created pysftp.walktree for walking local directories
    • added param recurse to .pysftp.Connection.walktree to allow it to do another trick
    • created .put_d to put the contents of a local directory to a remote one
    • created a context manager chdir method,
    • created .put_r to recursively put the contents of a local directory to a remote one
    • fixed a bug with .st_mode_to_int on py3 (#52)
    • .listdir_attr now returns a sorted list, sorted on filename
    • created with-context version of os.chdir for local directories
    • created docs, cookbook to show off some of the notable features of pysftp
  • 0.2.7 (released 2014-05-24)
    • created pysftp.Connection.walktree, recursively walk, depth first, a remote directory structure. Used as the base of .get_r. See tests/ for examples.
    • added .unlink as synonym for .remove
    • added .normalize
    • created .get_r to recursively copy remote directories to a local path
    • created .pwd to return the current working directory
    • created .cwd as synonym for .chdir
    • modified .listdir to return a sorted list instead of an arbitrary one
    • added .readlink, always returns an absolute path
    • created .get_d to copy the remote directory to a local path (non-recursive)
    • added .timeout to set the read/write timeout of the underlying channel for pending read/write ops
    • added .listdir_attr, wrapper for paramiko method
    • added .truncate, method returns the new file size
    • improved DRY’ness of test suite
  • 0.2.6 (released 2014-05-17)
    • added preserve_mtime parameter to .put, optionally updates the remote file’s st_mtime to match the local file.
    • added preserve_mtime parameter to .get, optionally updates the local file’s st_mtime to match the remote file
    • added .exists and .lexists, use .stat and .lstat respectively
    • added .symlink
    • created .isdir, .isfile, .makedirs
    • added .chmod
    • added .chown
    • added .sftp_client which exposes underlying, active SFTPClient object for advance use
  • 0.2.5 (released 2014-05-15)
    • added ciphers parameter to .Connection object (D. Reilly)
    • added .active_ciphers to return local and remote cipher in use
    • added .security_options, where you can get available ciphers, among other information
    • enhanced logging, and added documentation and tests
  • 0.2.4 (released 2014-05-13)
    • .Connection can be used in a with statement
    • add .remove
    • added support for callback and confirm params to .put
    • added support for callback on .get
    • added support for .open
    • fixed password bug and now differentiates between an empty string and None
    • added support for paramiko.AgentKey to be passed in as the private_key for Connection
    • added support for .mkdir
    • added support for .rmdir
    • added support for .stat and .lstat
    • added helper function, .st_mode_to_int,to convert the st_mode value back into a common integer representation
    • added .getfo
    • added .putfo
  • 0.2.3 (released 2014-05-10)
    • host code on pypi to keep pip happy
    • move code to bitbucket
    • enhance testing
    • README.rst and LICENSE named properly
    • cleaner error handling
  • 0.2.2
    • additions
      • chdir(self, path) - change the current working directory on the remote
      • getcwd(self) - return the current working directory on the remote
      • listdir(self, path=’.’)return a list of files for the given path

Release historyRelease notifications RSS feed










Pysftp Private Key

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pysftp, version 0.2.9
Filename, sizeFile typePython versionUpload dateHashes
Filename, size pysftp-0.2.9.tar.gz (25.9 kB) File type Source Python version None Upload dateHashes

Hashes for pysftp-0.2.9.tar.gz

Pysftp No Hostkey

Hashes for pysftp-0.2.9.tar.gz
AlgorithmHash digest