<type>how-to</type>
<domain>install</domain>
<id>wsl</id>
<title>Using Wing Pro with Windows Subsystem for Linux</title>
<date>$Date: 2006-12-28 17:21:05 -0500 (Thu, 28 Dec 2006) $</date>
<product>pro+</product>
<summary>Learn how Wing Pro speeds up development and debugging of Python code
running under Windows Subsystem for Linux.</summary>

.. image:: /images/screenshots/wing7-screenshot-linen.png
  :alt: Wing Screen Shot
  :width: 574
  :height: 423
  :popup: 1

`Wing Pro <https://wingware.com>`__ is a Python IDE that can be used to develop, test, and
debug Python code running on `Windows Subsystem for Linux
<https://docs.microsoft.com/en-us/windows/wsl/about>`__ (WSL).

This document describes how to configure Wing Pro for WSL. To get started using Wing Pro
as your Python IDE, please refer to the tutorial in Wing's ``Help`` menu or read the
`Quickstart Guide <ref:howtos/quickstart>`__.

Prerequisites
-------------

To use Wing Pro with `WSL <https://docs.microsoft.com/en-us/windows/wsl/about>`__ you will
need to install Python on WSL and be able to SSH from Windows into WSL. If you don't already
have this working, see ``Setting up WSL`` below before trying to create a project in Wing Pro.

If you do not already have Wing Pro installed, `download it now
<https://wingware.com/downloads/wingpro>`__.

Creating a Project
------------------

To create a Wing Pro project that accesses Linux under WSL:

(1)  Make sure WSL is running by typing ``wsl`` on the Windows command line. Then make sure
     the SSH server is running, for example on Ubuntu with ``sudo service ssh --full-restart``.
     You will want to leave ``wsl`` running as long as you are using Wing with WSL. Otherwise,
     Wing will not be able to connect to it.
(2)  Use ``New Project`` from the ``Project`` menu in Wing Pro and then select ``Create Configuration``
     from the ``Host`` menu in the ``New Project`` dialog.
(3)  Set the ``Remote Host Type`` in the ``New Remote Host`` dialog to ``WSL``.
(4)  Set ``Host Name`` to the ``username@ipaddress`` with which you can connect from Windos
     to WSL using either ``ssh.exe`` or ``plink.exe``.  Replace ``username`` with
     the user name running on Linux and ``ipaddress` with the IP address
     that ``ip a`` reports inside your WSL system.  The user name is needed even if it is the 
     same as the user running on Windows.
     
In some (mostly rare) cases you may also need to:

(5)  Set ``Python Executable`` to ``Command Line``to the full path of the Python executable 
     that you wish to use on Linux, if the auto-filled default value ``/usr/bin/python3`` is 
     not correct.
(6)  Change the starting port listed by ``Remote Debug Ports`` under the ``Advanced``, if
     the default value of ``50050`` cannot be used.
(7)  If you are running the SSH server on Linux under a non-standard port, set ``SSH Port`` 
     under the ``Options`` tab.
(8) If you are using an older WSL version that allows connecting with ``username@127.0.0.1``
    then you will also need to set ``Manage SSH Tunnels`` under the ``Advanced`` tab of the 
    remote host configuration to ``Never Create Tunnel``.  This should *not* be done if
    using an IP address other than ``127.0.0.1`` in the ``Host Name`` field.

After submitting the ``New Remote Host`` dialog, Wing should install the
remote agent on your WSL Linux and confirm that it is working. Then you can
continue through the ``New Project`` dialog to select or create your source
directory and select or create the Python environment to use. See `Creating a
Project <ref:proj/creating-a-project>`__ for details.

Once this is done, you will be able to edit, debug, test, search, and manage files on the
WSL-hosted Linux installation, or launch commands running on Linux from Wing Pro's ``OS
Commands`` tool.

To learn more about Wing Pro's remote development capabilities, see `Remote Hosts 
<ref:proj/remote-hosts>`__.

To learn more about Wing Pro's features, take a look at the Tutorial in Wing's ``Help``
menu or the `Quickstart Guide <ref:howtos/quickstart>`__.

Setting up WSL
--------------

Here is one way to set up WSL with Ubuntu as the Linux distribution and PuTTY as the SSH
client:

**Enable WSL and Install Ubuntu Linux:**

* Enable WSL in Windows.  This is done in the Settings app, on Windows 11 under Apps > 
  Optional features > More Windows features and on Windows 10 under Apps > Apps & features >
  Related settings / Programs and features > Turn Windows features on and off.  Restart
  Windows when prompted.
* Install Ubuntu from the Microsoft Store.
* Connect to WSL by typing ``wsl`` on the command line in Windows and check whether 
  ``python3`` is installed.  If not, install it with ``sudo apt-get install python3``

**Fix the SSH server on Ubuntu:**

* Some versions of Ubuntu under WSL seem to be initially misconfigured so that connecting
  to the SSH server immediately drops the connection.  If you run into this, you can fix
  the problem by running ``wsl`` on Windows to connect to WSL and then on Ubuntu type
  ``sudo apt-get purge openssh-server`` followed by ``sudo apt-get
  install openssh-server`` and then ``sudo service ssh --full-restart``.

**Each time you restart Windows or Ubuntu**

* Run ``wsl`` to start WSL's Linux running.  You must leave this running as long as Wing is
  accessing WSL.
* Run ``sudo service ssh --full-restart`` on Ubuntu to make sure the SSH server is started.

**Find the IP Address for Ubuntu**

* Run ``wsl`` on Windows
* In the resulting WSL prompt, run ``ip a`` to get the IP address for ``eth0``.  For example, in the 
  following output fragment the IP address is ``172.17.134.127`` (the number right after ``inet`` in 
  the ``eth0`` section)::
  
    4: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
      link/ether 00:15:5d:a8:d9:33 brd ff:ff:ff:ff:ff:ff
      inet 172.17.134.127/20 brd 172.17.143.255 scope global eth0
         valid_lft forever preferred_lft forever

Now you should be able to connect to Ubuntu from Windows using ``username@ipaddress``, with
``username`` replaced with your Ubuntu-side user name and ``ipaddress`` replaced by the IP
address you just found. You can try this with PuTTY's ``plink.exe`` or OpenSSH's
``ssh.exe`` if you have that, or proceed to creating your Wing project (see above) to use
Wing's built-in SSH implementation.

Note that these instructions are for Ubuntu.  Other Linux distributions that are also available 
in the Microsoft Store may require different commands to complete the above steps.

Trouble-Shooting
----------------

Remote development to WSL can be slow or unreliable if there are one or more SSH keys on
your host system (where the IDE is running) that are not accepted by WSL. This results in
Wing trying to use those keys in order, each being rejected, before prompting for a login
password. Even after passwords are entered, non-working keys may be tried, slowing down
the connection time considerably, or preventing connection from occurring before network
timeouts are reached.

If you are having this problem, you can solve it by setting ``Private Key`` under the
``Options`` tab in your remote host configuration, accessed via ``Remote Hosts`` in the
``Project`` menu.  This ensures the correct key is tried first.

An alternative solution that may also work is to place your SSH public key in the file
``~/.ssh/authorized_keys`` on WSL, so that the key is accepted. Note that if you are using
PuTTY, you will need to convert your key to OpenSSH format using ``puttygen``. See
`Working with PuTTY <ref:proj/ssh-setup-details-putty>`__ for details.

For details on diagnosing and fixing other problems with remote development, please see
`Trouble-Shooting Remote Development Problems <ref:proj/remote-trouble>`__.

Related Documents
-----------------

For more information see:

* `Windows Subsystem for Linux <https://docs.microsoft.com/en-us/windows/wsl/about>`__
  provides information on getting starting with WSL.
  
* `Remote Hosts <ref:proj/remote-hosts>`__ for details on configuring remote development.

* `Quickstart Guide <ref:howtos/quickstart>`__ contains additional basic information
  about getting started with Wing Pro.
  
* `Tutorial <ref:intro/tutorial>`__ provides a gentler introduction to Wing Pro's features.

* `Wing Pro Reference Manual <ref:manual>`__ documents Wing Pro in detail.

