Wing IDE can work with Python code that is stored on a remote host or device in the same way as you work with code stored locally. This includes the editing, debugging, testing, search, version control, Python Shell, OS Commands, and project management features.
Remote development is supported to OS X and Linux. A detailed list of supported remote host types is on the Supported Platforms page.
Setting up SSH
To work with a remote host, first set up secure SSH remote access to the remote host from outside of Wing IDE. You should configure this so you can ssh to the host without having to enter a password each time you connect. Instead, you want authentication to occur using an SSH key, and by entering your password once to load the key into an authentication agent. On Linux and OS X this is done with the standard SSH tool suite that comes with the OS. On Windows, this is done with PuTTY. If you do not already have this set up, or you cannot SSH to the remote host without entering a password every time you connect, please refer to SSH Setup Details before going any further.
Once you have SSH working outside of Wing, and can connect to the remote host without entering a password for each connection, start Wing in an environment where it will be able to access the SSH keys stored by ssh-agent (on Linux), Keychain Access (on OS X), or pageant.exe (on Windows).
Wing uses the following command line tools to implement secure access to remote hosts: ssh and scp (on Linux and OS X) or plink.exe and pscp.exe (on Windows).
Wing tries to find these SSH tools on the PATH on the machine where Wing IDE is running, and on Windows it also searches for PuTTY in common installation locations if it cannot find it on the PATH.
If Wing cannot find ssh or plink.exe you will need to add their installation directories to your PATH or set the Network > SSH Executable preference to the full path of the command. If this is set, Wing also tries to find scp (or pscp.exe on Windows) in the same directory as the specified executable.
Configuring Remote Hosts
Remote hosts are confgured using the Remote Hosts item in the Project menu. The following values may be specified:
Identifier -- (Required) This is the unique permanent name used to reference this remote host configuration. It is used in the URLs that reference resources on the remote host. If a remote host configuration's ID is changed, Wing will track that change in all the remote host references stored in the project.
Host Name -- (Required) This is the remote host's DNS name or IP address. The the hostname should include the username, in the form username@hostname or username@ipaddress if the user name on the remote host is different from the user on the local host. If this field is changed in an existing remote host configuration, Wing will try to find remote resources on the new host name.
WINGHOME -- (Required) This is the full path to the installation location of Wing IDE on the remote host. If Wing IDE is not already installed there, Wing will offer to install the necessary files so that remote development will work.
Python Executable -- This is the Python to use for running Wing's remote agent and for debugging or executing remotely. This can be left blank if python can be found on the PATH and is a supported version of Python. Otherwise, it should be the name of a Python that can be found on the PATH, the path relative to the configured base directory to a Python executable, or the full path to the Python executable.
Base Directory -- This is the directory on the remote host from which all file references are made, so that Wing will show only the relative path from the configured base directory. By default, it is the remote user's home directory. If this value is changed on an existing configuration, Wing will try to find resources relative to the new base directory.
Remote Agent Port -- This is the TCP/IP port to use for the remote agent on the remote end of the SSH tunnel. When this is not specified, Wing uses a random port number determined on the IDE side of the connection. This usually works but there is no guarantee that the port will also be available on the remote end. When set, this property should be an unused unprivileged ephemeral port number (usually between 1025 and 65535 on Windows, 32768 and 61000 on Linux, and 49152 and 65535 elsewhere).
Remote Debug Port -- This is the first TCP/IP ports to use for the debugger on the remote end of the SSH tunnel. By default, as for Remote Agent Port, a random port is used. When a value is specified, Wing uses only ports starting with the given port, up to however many ports are needed for active debug sessions and Python Shells.
After a remote host is configured, Wing will try to connect to that host and run its remote agent, and will offer to install the remote agent if it is not found. The remote agent is started or restarted as needed and will exit after a timeout period if it is unused. The remote agent allows Wing to search, inspect, read, and write files and directories, create or delete files, start debug or execution, run unit tests, invoke version control operations, run Python Shell, invoke commands in OS Commands, and perform other actions on the remote host to support the IDE's functionality. The necessary SSH tunnels for communication to the remote agent and to support debugging files remotely are also managed automatically.
You can find a log of the remote agent's activities in the file remote-agent.log within the User Settings Directory on the remote host.
Shared Remote Hosts Configurations
Remote host configurations can either be stored in the project file or shared in the User Settings Directory so they can be accessed from all projects. To make a remote host configuration shared, check the Shared box for that configuration in the remote host manager access from the Project > Remote Hosts menu item.
In general, a shared remote host configuration should be used when the project file is stored on the remote host, and non-shared remote host configurations should be used when a project file is stored locally but accesses resources on a remote host.
There are two ways to work with remote hosts: (1) a locally stored project file can reference remote resources, and (2) a project file stored on a remote host and opened remotely can transparently access resources on that remote host.
Local Project Files
For projects stored locally that need to access resources on another host, the Python Executable property in Project Properties is set to Remote to indicate that a project's Python resides on a remote host. The remote host configuration that is selected is typically an unshared configuration, so that it is stored in the project and will be accessible if the project is moved to another machine. Note, however, that remote host configurations may be specific to an individual machine's network environment, and may need to be edited on other hosts.
After Python Executable has been set, other properties that reference files (such as Initial Directory and Python Path) will be resolved on the remote host. The Browse buttons for those properties will browse the remote host, and paths will be stored as partial paths relative to the configured Base Directory or as full paths if located outside of the Base Directory. Paths on remote hosts are always expressed using forward slash / and will be converted as needed to the native separator on the remote host.
The selected remote host will also be used for adding files and directories to the project. When a URL for a remote file or directory is shown, it will be in the form ssh://hostid/path/to/file.py where hostid is one of the configured Remote Host IDs.
A locally stored project can include files and directories on multiple hosts, by adding several hosts and using Add Existing File and Add Existing Directory with each host.
Remote Project Files
Projects stored on a remote host are opened with Open Remote Project in the Project menu. In this case, they are accessed through a shared remote host configuration. Projects stored like this are normal Wing projects and may also be opened locally, if Wing can also be run on the remote host itself. In this case, Python Executable is simply set to Default or Custom, as if the project were stored locally. Wing resolves all the resources in the project file in a way that allows it to access them on the host where the project is stored.
If any remote host configurations are added to a remotely stored project, in order to access other remote hosts, those configurations must work on the host where the IDE is running.
Creating Project Files
To set up a new project that accesses a remote host, use New Project in the Project menu and specify Connect to Remote Host (via SSH) as the project type. This will ask for the same fields described above for creation of a remote host configuration. If you have already created a configuration previously, use the Recent Hosts drop down to copy that configuration.
The New Project dialog will offer to save the project either locally or on the selected remote host. If it is stored locally, the entered remote host configuration will be stored in the project file. If it is stored remotely, the configuration will be set up as shared so it is always accessible on the local machine, even if the remote project is not open.
A regularly created local project can also be moved to a remote host with Save Project On Remote Host` in the Project menu. However, this moves only the project file itself, and assumes that resources references by the project will also be available on the remote host, with the same relative paths from the project file.
Working with Remote Hosts
Once you have set up a project with remote files, you can start debugging one of those files in the same way that local files are debugged. Wing will initiate the debug connection automatically through its SSH tunnels to the remote host. Filenames will be shown in the form hostid:filename but otherwise debugging works the same way as if it were on the local host.
To debug on several different remote hosts, use Launch Configurations in the Project menu to create debug configurations on each host. This is done in the same way as for Project Properties (by setting Python Executable under the Python tab to Remote). Then set up a Named Entry Point that pairs a file on that remote host with a launch configuration for the same remote host.
Whether you use the Project-wide settings or a launch configuration, the file you debug needs to be stored on the selected remote host. You cannot debug a file from one host on another host using this style of remote debug configuration.
Note that the Debugger > External/Remote preferences are not used when debugging remotely using configured remote hosts. Instead, Wing is establishing an SSH tunnel that makes both the debug process and IDE appear to be running on the same host.
The Debugger > Diagnostics preferences are also not used when debugging remotely using remote hosts. The following environment variables can be used instead to collect debugger diagnostics. These should only be used at the request of Wingware Technical Support and the resulting log file can be emailed along with your bug report to firstname.lastname@example.org:
WINGDB_LOGFILE -- This can be used to set up a diagnostics log file when trouble- shooting problems with the debugger. The environment variable should be set to the full path of the log file on the remote host.
WINGDB_LOGVERYVERBOSE -- Whether to print extremely verbose low-level logging. This is almost never needed and will drastically slow down debugging.
Once you have set Python Executable in Project Properties to a remote host, you can restart the Python Shell from its Options menu to launch a shell that is running on the remote host.
If remote files have been added to the Testing tool the unit tests can be run or debugged as if they are on the same host as the IDE.
If remote files are checked into a version control system, Wing should identify this as it does for local files and include the appropriate tools in the Tools menu. Version control features work the same way for remote files as for local files. However, it may be necessary to configure version control for the remote host using the VCS tab in Project Properties.
The OS Commands tool also supports working remotely with the Hostname property under the Environment tab of Command Line style commands. For Python File and Named Entry Point style OS Commands, the host name is inferred from the location of the file being executed.
This release only supports working with OS X, Linux, and Raspberry Pi remote hosts. Attaching to Windows as the remote host does not work yet.
Also, Compare Directories does not work with directories in a remote host. However, other comparison features, including Compare to Revision, do work.
3.9.0. SSH Setup Details