<type>how-to</type>
<domain>howtos</domain>
<id>virtualenv</id>
<title>Using Wing with virtualenv</title>
<date>$Date: 2012-11-15 15:25:42 -0500 (Thu, 15 Nov 2012) $</date>
<version>$Revision: 27651 $</version>
<product>per+</product>

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

`Wing <https://wingware.com>`__ is a Python IDE that can be used to develop, test, and
debug Python code running in `virtualenv <http://www.virtualenv.org>`__.

Two versions of Wing are appropriate for use with this document: Wing Pro is the
full-featured Python IDE for professional developers, and Wing Personal is a free
alternative with reduced feature set.

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

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

Creating a New Virtualenv
-------------------------

If you are starting a new project from scratch and want to create a new virtualenv for the
project, select `New Project <script:new-project>`__ from the ``Project`` menu and use the
``Create New Virtualenv`` project type. You will need to enter the following values:

  ``Name`` is the name for your virtualenv directory.
  
  ``Parent Directory`` is the directory where the virtualenv directory will be created.
  
  ``Python Executable`` selects the base Python installation to use.  In Python 2,
  you must install virtualenv into the selected Python first, if it's not already present.
  
  ``Inherit global site-packages`` controls whether to use the ``--system-site-packages``
  option when running virtualenv. When checked, the virtualenv will be able to use
  packages installed into the base Python installation. Otherwise, it will be completely
  isolated from the base install, other than its use of Python's standard libraries.
  
  ``Auto-save project`` controls whether Wing automatically saves its project file to the
  virtualenv directory. When checked, the project is named using the ``Name`` entered
  above plus ``.wpr`` and is stored in the top level of the virtualenv directory. In Wing
  Pro, which separates sharable project data from user-specific data, a second file ending
  in ``.wpu`` will also be written.

After submitting the ``New Project`` dialog, Wing will create the virtualenv, set the
`Python Executable <script:view_project_properties#highlighted_attrib="proj.pyexec">`__ in
``Project Properties`` to the ``python`` inside the virtualenv directory, and add the
virtualenv directory to the project.

Now source analysis, executing, debugging, and testing in Wing will use the new
virtualenv, as long as the project you just created is open. You will need to restart the
``Python Shell`` tool in Wing before it uses the newly created virtualenv.

~~~if WINGPRO:
Working on a Remote Host
........................

Wing Pro can also create a new virtualenv on a remote host.  This is done the same
way as described above, except you will choose ``Remote`` for ``Python Executable``
and then select or create a remote host configuration.  The Python used for creating
and running the virtualenv on the remote host is the one chosen in the remote host 
configuration's ``Python Executable``.

If you check ``Auto-save Project`` you will need to mark your remote host configuration as
shared in the remote host configuration management dialog, which can be accessed from
``Remote Hosts`` in the ``Project`` menu or with the ``Manage`` button under ``Python
Executable`` in the ``New Project`` dialog. This is needed so remote host configuration is
stored locally, while the project will be stored on the remote host.
~~~

Using an Existing Virtualenv
----------------------------

To use an existing virtualenv with Wing, simply set the `Python Executable
<script:view_project_properties#highlighted_attrib="proj.pyexec">`__ in Wing's ``Project
Properties`` to the ``python`` inside your virtualenv directory. Wing uses this to
determine the environment to use for source analysis and to execute, test, and debug
your code.

The easiest way to find the correct value to set is to launch your virtualenv Python
outside of Wing and run the following interactively::

  import sys
  sys.executable

Use the full path that prints as the ``Python Executable`` in Wing.

Activating the Virtualenv
-------------------------

If you follow the above instructions, Wing will automatically activate the virtualenv
while you're using your project.

An alternative approach is to leave ``Python Executable`` unset and instead activate the
virtualenv on the command line and then start Wing from the command line so that it
inherits the virtual environment. However, setting ``Python Executable`` is preferable so
that Wing switches virtual environments when you switch projects, without restarting the
IDE.

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

For more information see:

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

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

