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

~~~if WINGPRO:
To create a new project, use ``New Project`` in the ``Project`` menu. This dialog prompts
you to select or create a source directory to use with your new project (either on the
local host or a remote system), and to select or create a Python environment. You will
also be able to specify a revision control repository to clone into a newly created
directory, and any packages to install into a newly created Python environment. The Python
environment may be a base Python install, a virtualenv, an environment managed by uv, Poetry, or pipenv, an Anaconda
env, or an container environment managed by Docker, Docker Compose, Vagrant, or LXC/LXD.
~~~
~~~if WINGPER:
To create a new project, use ``New Project`` in the ``Project`` menu. This dialog prompts
you to select or create a source directory to use with your new project, and to select
a Python environment.
~~~

~~~if WEBSITE:
Note that Wing Personal omits the ability to create a new Python environment from
the ``New Project`` dialog and can only work with files and projects on the local host.
~~~

~~~if WINGPRO:
Select the Host
---------------

The first step is to select the host where your source directory will be located. The
default is the local host. Any remote host, VM, or container that is accessible by ssh may
also be used with Wing's `remote development <ref:proj/remote-hosts>`__ capability. If you
wish to access a remote system for which you don't already have a remote host
configuration, you can add one with ``Create Configuration`` in the ``Host`` popup menu.

Note that if you are using containers you will want to select ``Local Host`` since the
master copy of your source directory is stored locally. You can configure and select the
containerized Python environment later in the project creation process.
~~~

Select the Source Directory
---------------------------

~~~if WINGPRO:
Next you will select whether you plan to use an existing source directory or create a
new one.  The options are:
~~~
~~~if WINGPER:
The first step is to select whether you plan to use an existing source directory or create a
new one.  The options are:
~~~

**(1)** ``Create Blank Project`` creates a new empty untitled project for subsequent manual
configuration. When this value is selected the dialog's ``Next`` button is replaced with
``Create Project`` and the project is created immediately from there.

**(2)** ``Use Existing Directory`` allows you to select an existing source directory from the host
selected above. This directory will be added to your project and scanned to detect whether
it implies the Python environment that should be used by your project. If a virtualenv is
found in the top level of the directory, in ``.venv`` or ``venv`` inside the directory, or if 
the directory is managed by ``uv``, ``Poetry``, or ``pipenv``, then Wing changes the ``Next`` button in the dialog 
to ``Create Project`` and creates the project immediately using the found Python environment.

**(3)** ``Create New Directory`` -- will create a new directory with selected name and parent
directory.  You may optionally choose to clone a revision control repository into
the new directory and select a test framework to use with it.

Whether using an existing directory or creating a new one, ``Project Type`` may be
selected for certain commonly used Python frameworks. This causes Wing to configure the
project in ways specific to that framework. For example, for ``Flask`` child process
debugging is enabled so Flasks's reload feature may be used with Wing's debugger,
``Django`` enables debugging of Django templates, and ``SciPy`` and others enable special
support for interactive plots.

~~~if CLAUDECODE:
The **Set Up for Claude Code** option writes an ``.mcp.json`` file into the project source
directory so that `Claude Code <https://claude.ai/code>`__ can access Wing features such
as the debugger via MCP. See `Using Wing Pro with Claude Code <ref:howtos/claude-code>`__
for details.
~~~

Select the Python Environment
-----------------------------

~~~if WINGPRO:
Unless you are creating a new blank project or using an existing directory that implies
the Python environment to use, you will be presented with options for selecting or
creating a Python environment after pressing the ``Next`` button in the ``New Project``
dialog.  The options here are:

**(1)** ``Use Existing Python`` selects an existing Python installation, virtualenv or Anaconda
environment, or an existing container or cluster such as those provided by Docker, Docker
Compose, and LXC/LXD.
~~~
~~~if WINGPER:
Unless you are creating a new blank project or using an existing directory that implies
the Python environment to use, you will be presented with options for selecting or
creating a Python environment after pressing the ``Next`` button in the ``New Project``
dialog.  The options here are:
~~~

``Use Default`` selects the latest found Python version on your system.

~~~if WINGPRO:
.. note::

  If you selected a remote host on the previous screen, ``Use Default`` is replaced with
  ``Use Remote Host Config``, which causes Wing to use the Python that you selected when
  you set up your remote host configuration. In this case, no other option to select an
  existing Python is present, but you can create a new environment as described under (2)
  below.
~~~

``Command Line`` is used to select an existing base installation of Python. You will need
to enter the full path to the ``python``, ``python2``, ``python3``, or ``python.exe``
executable. This is the value of ``sys.executable`` after ``import sys`` in the Python you
wish to use. Wing presents a menu of found Python installations in the drop down to the
right of the entry area.

``Activated Env`` activates and uses a virtualenv or Anaconda environment.  You will need to
enter the full path to the ``activate`` or ``activate.bat`` for a virtualenv, or the
Anaconda environment's activate command. Recently used and found environments are listed in
the drop down menu to the right of the entry area.  Note that an activated env will not work
if the full path to the activate command contains spaces.  In that case, use the 
``Command Line`` option as described above.

~~~if WINGPRO:
``Container`` uses an existing Python container managed by Docker or LXC/LXD. You will
need to select an existing container configuration or add a new one with the ``New``
button. Adding a new configuration here tells Wing how to use your existing container but
does not create a new container environment. To create a new container environment, select
``Create New Environment`` as described below.

``Cluster`` works in a similar way, but for clusters of Python containers managed by
Docker Compose.

See `Working with Containers and Clusters <ref:proj/container-intro>`__ for more
information on using containers and clusters in Wing Pro.

**(2)** ``Create New Environment`` creates a new Python environment along with your project.  
You can select the type of environment from the popup that appears when this option is chosen.
Environments may be managed by virtualenv, uv, Poetry, pipenv, Anaconda's conda, or Docker.  Each of
these choices displays a different environment creation form, as described in the next
section.
~~~

