<type>documentation</type>
<domain>proj</domain>
<id>creating-a-project</id>
<title>Creating Python Environments</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

Wing Pro can create a number of different kinds of Python environments along with your
project: virtualenvs, Poetry envs, uv envs, pipenvs, Anaconda envs, or Docker containers. These are selected
from the drop down menu next to ``Create New Environment`` on the second page of the ``New
Project`` dialog. Wing presents different configuration options for each type of
environment, as detailed below.

**Creating a Virtualenv**

You will be prompted for the name and parent directory of the new virtualenv. The name
defaults to the name of the new or existing source directory chosen earlier in the ``New
Project`` dialog, and the parent directory defaults to a central location inside Wing's
`Settings Directory <ref:proj/user-settings-dir>`__ or the most recently used directory.

You can use ``Packages to Install`` to select any packages you want to install while
creating the new environment. This may be done by entering the `package specifications
<https://www.python.org/dev/peps/pep-0440/#version-specifiers>`__ or selecting an existing
``requirements.txt``, ``Pipfile``, or Anaconda environment.yml.

.. note::

  **Important!** Please note that careless package selection may install malware on your
  computer.  Be sure to read and understand `Package Security <ref:packages/security>`__
  before installing any packages!

The ``Python Executable`` is used to select the base Python installation to use with the
new virtualenv.  This determines the Python version that will be used.

Selecting ``Upgrade pip`` causes Wing to upgrade ``pip``, the Python package manager,
after setting up the virtualenv. This is recommended since virtualenv usually installs an
outdated version of ``pip``.

Checking ``Inherit global site-packages`` can be used to allow the virtualenv access to
packages that have been installed into the selected base Python installation. This is not
recommended because it may defeat the primary purpose of virtualenvs, to provide a uniform
replicable environment.

When a new virtualenv environment is created, Wing writes a ``requirements.txt`` file for
package management into the selected source directory. In Wing Pro, subsequent package
installation, removal, upgrade, and inspection is possible through the `Packages
<ref:packages/intro>`__ tool, which will maintain the ``requirements.txt`` file on
request.

**Creating Poetry, uv, and pipenv Environments**

`Poetry <https://python-poetry.org/>`__, `uv <https://docs.astral.sh/uv/>`__, 
and `pipenv <https://pipenv.pypa.io/>`__ are tools
that automate and simplifie maintenance of a virtualenv and package management in that
environment, with focus on the ease of replication of identical package environments for
developers working on the same source base. Theyt can be used to create and manage a new
virtualenv for either an existing or newly created source directory. Since Poetry, uv, and
pipenv manage the virtualenv automatically, there is no option to select the location 
for the new virtualenv.

Any ``Packages to Install`` and Python Executable`` may be entered as described for
virtualenv above.

When Poetry creates a new environment, it will write ``pyproject.toml`` if not already
present and also the ``poetry.lock`` file into the selected source directory. These files
are used by Poetry to manage package installation, dependencies, and upgrades.

Similarly, ``uv`` creates ``pyproject.toml`` and ``uv.lock``, and pipenv creates `Pipfile`` and
``Pipfile.lock`` in the selected source directory.

**Creating an Anaconda Environment**

`Anaconda <https://www.anaconda.com/>`__ is a Python distribution that provides its own
package manager.  

Somewhat like Poetry, ``uv``, and ``pipenv``, the ``conda`` package manager can store its environments
in a hidden centrally managed location, allowing reference to them by name. To store the
environment elsewhere, set the ``Parent Directory`` to ``Selected Directory`` and enter
the full path of the parent directory for the new environment.

``Anaconda Installation`` is used to select the Anaconda base installation to use in
creating the new environment.

``Packages to Install`` selects any packages to install in the new environment, as
described for virtualenv above.

**Creating a Docker Environment**

There are two options for creating a new Docker environment along with your new project:
(1) You may use an existing already-created Docker container as your Python environment,
or (2) you may create a new Docker container along with your project and configure Wing to
use it. The former only creates a container configuration that allows Wing to access the
Docker container, while the latter also creates a new Docker container.

These options are described in detail in `Using Wing Pro with Docker <ref:howtos/docker>`__.
