Wing Tips: Developing and Debugging Python Code Running on Vagrant Containers

Sep 25, 2018

Vagrant provides a way to set up lightweight containers that are isolated from your host OS. Containers are very useful in software development because they are easy to share with other developers, so that everybody on a software development team is working with exactly the same coding environment.

However, since these containers are often fairly stripped down, developing and debugging on the container may not be as convenient as working on your regular development system.

One way to make this easier for Python is to set up remote development from Wing Pro. In this model, code is developed, tested, and debugged on the container from a copy of Wing Pro running on your regular desktop or laptop system.


This guide assumes you have already installed and started using Vagrant. Wing Pro supports working with Vagrant boxes running Linux (32-bit or 64-bit) or macOS. As of now, other OS types such as FreeBSD won't work.

You will also need to make sure that Python is installed in the Vagrant box. If Python is not present, Wing Pro's remote agent installation process will fail.

On Windows, you may need to install PuTTY or one of the OpenSSH ports if you don't already have this set up, so you can connect to the Vagrant container. See SSH Setup Details in Wing Pro's documentation for details.

If you do not already have Wing Pro installed, download it now.

Creating a Project

After you have started Wing Pro, creating a project for an existing Vagrant container is easy:

  • Start your container as usual, with vagrant up
  • Use New Project from the Project menu in Wing Pro and then select Connect to Vagrant as your project type
  • Fill in or browse to the full path of your Vagrant project directory which contains your Vagrantfile and press OK
  • Only on Windows with PuTTY, you will be asked to convert Vagrant's private key into a PuTTY key. To do this, Wing starts puttygen with the private key already loaded into it. Press Save private key to save the key as private_key.ppk in the current directory. Confirm saving without password (the original also doesn't have a password) and then quit puttygen to continue the project setup process in Wing.
  • Install the remote agent when prompted.

Once this is done, Wing should confirm that the remote agent installation is working.

Then you can add your source directories to the project with Add Existing Directory in the Project menu. Finally, use Save Project in the Project menu to write Wing Pro's project file to local disk.

You can now edit, debug, test, search, and manage files on the Vagrant container, or launch commands running in the container from Wing Pro's OS Commands tool. Even though Wing Pro is running on your host OS, everything you do takes place in the Vagrant container, as controlled by the remote agent.

If you have any problems getting this to work, feel free to email for help.

To learn more about Wing Pro's remote development capabilities, see Remote Hosts.

To learn more about Wing Pro's features, take a look at the Tutorial in the Help menu or the Quickstart Guide.

How It Works

Wing uses vagrant ssh-config to inspect your Vagrant container and fill in the necessary settings in Wing's project file. Then all communication with the container is through SSH.

To see the settings that Wing created during New Project, take a look at Project Properties from the Project menu. The Python Executable was set to point to a remote host named vagrant. Click on Edit here or use Remote Hosts in the Project menu to access the remote host configuration. The values that Wing sets up are: Identifier, Hostname, and WINGHOME under the General tab, and SSH Port and Private Key under the Options tab. Settings these values manually achieves exactly the same result as using New Project.

The installation process will also add the Vagrant container's SSH host key as a known host in ~/.ssh/known_hosts or in the registry if using PuTTY on Windows.

Usage Hints

Selecting the Python Installation

In cases where Wing is not picking up the right Python to use automatically, for example if multiple installations of Python are present on the Vagrant container, you can select the correct one with Python Executable in the remote host configuration, which you can access from Remote Hosts in the Project menu.

To check that the correct installation is being used, select Restart Shell from the Options menu of the Python Shell tool and type the following in the shell:

import sys

Synced Folders

As far as Wing is concerned, all files and directories are located in the Vagrant container and Wing never accesses local copies of the files maintained by Vagrant's synchronization commands.

If you need to update your local copies of files for some other reason while working with Wing, run vagrant rsync, or set up continuous synchronization with vagrant rsync-auto.

Password-less Private Keys

Vagrant uses password-less private keys by default. If you want to use private keys with passwords, you'll need to load the key into the SSH user agent (ssh-agent or pageant for PuTTY) and change Options > Private Key in Wing's vagrant remote host configuration to Use SSH User Agent.

Related Documents

For more information see:

Share this article: