<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>pro+</product>

.. 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 in `virtualenv <http://www.virtualenv.org>`__.

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

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
-------------------------

Wing Pro can create a new virtualenv at the same time that you create a new project.
To do this, select ``New Project`` from the ``Project`` menu, choose the source directory
to use with your new project, and then press ``Next``.  On the second page you will 
be able to select ``Create New Environment`` and choose ``virtualenv`` from the menu
of available environment types.

If you are using an existing source directory, 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.
  
If you are using a new source directory, the virtualenv will be created inside
that new directory.

You may also specify the following values:

  ``Packages to Install`` lets you specify packages to install into the new virtualenv.  This is
  either a space-separated list of pip package specifications, or a file that contains
  one package specification per line.  In either case, the package specifications may
  be anything accepted by pip, such as a package name, ``package==version``, and 
  ``package>=version``.
  
  ``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.
  
  ``Upgrade pip`` selects whether Wing should upgrade pip in the virtualenv before
  installing any packages, to compensate for the fact that virtualenv installs
  an old version of pip even if the base Python installation has a newer one.
  
  ``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.

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 command that activates the environment, 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.

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 first need to choose or create a remote host 
configuration from the ``Host`` menu on the first page of the ``New Project`` dialog.

If you are using a virtualenv on the remote host, Wing will update the remote host
configuration to use that virtualenv.

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`` or the ``New Project`` dialog to ``Activated Env`` and enter the command that
activates the environment. Wing uses this to determine the environment to use for source
analysis and to execute, test, and debug your code. In this case, Wing starts Python by
running ``python`` in that environment.  This does not work, however, if the full path
to the activate script contains a space.  In that case, use ``Command Line`` instead,
as described below.

``Python Executable`` can also be set to ``Command Line`` to enter the full path to the
virtualenv's ``python.exe`` or ``python``.  In fact, this is required if the full path to the
activate command contains spaces.  The easiest way to find the correct value to
set is to launch your virtualenv Python outside of Wing and execute the following:

.. python::

  import sys
  print(sys.executable)

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

If you followed 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, this is not recommended because the inherited
environment may conflict with virtual environments used by other projects.

Package Management
------------------

Once you've configured your project to use a virtualenv, you can use the ``Packages`` tool
in the ``Tools`` menu to list, add, remove, or update packages. See `Package Manager
<ref:packages/intro>`__ for details.

Using Virtualenv with Anaconda
------------------------------

Anaconda implements its own named environments, created by ``conda create`` but it is also
possible to use virtualenv with Anaconda. This works in the same way, except that on
Windows Wing will automatically call ``conda activate base`` before it sets up your
virtualenv. This is needed to avoid failure to import some modules as a result of missing
environment. See About Anaconda Environments in the `Anaconda How-To
<ref:howtos/anaconda>`__ for details.

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.

