<type>documentation</type>
<domain>proj</domain>
<id>intro</id>
<title>Package Manager</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

Wing Pro's `Packages <script:show-panel-packages>`__ tool, available in the ``Tools``
menu, provides integrated Python package management with ``conda``, ``pip``, ``pipenv``,
``poetry``, or ``uv``.

Configuration
-------------

Wing expects any package configuration files to be in the same directory as the Wing project
file or the directory configured with ``Project Home Directory`` under the ``Options`` tab
in ``Project Properties``.  The files are:

* With pip or conda, ``requirements.txt``
* With pipenv, ``Pipfile`` and ``Pipfile.lock``
* With Poetry, ``pyproject.toml`` and ``poetry.lock``
* With uv, ``pyproject.toml`` and ``uv.lock``

Using a ``requirements.txt`` with ``pip`` and ``conda`` is optional, but when present Wing
can keep the file updated to reflect the packages that have been installed, removed, or
updated.

Wing can install the package managers but make some assumptions:

* For all but ``uv``, Wing assumes that ``pip`` is already present in your selected Python 
  installation. In the rare cases that it is not, you must install it manually, using 
  `getpip.py <https://github.com/pypa/get-pip>`__ or other solution.
  
* For ``uv``, Wing assumes ``pipx`` is already installed.  See the ``pipx`` documentation for
  details on how to install it on your system.

To set up package management, you need to first create a Wing project, configure the
``Python Executable`` either from the ``New Project`` dialog or the ``Environment`` tab in
``Project Properties``, and then save the project to disk.

Once you save your project, Wing tries to auto-detect the package manager. It will select ``uv`` if
``uv.lock`` is present, poetry`` if ``poetry.lock`` is present, ``pipenv`` if ``Pipfile`` is
present, ``conda`` if the selected ``Python Executable`` is found to belong to a found Anaconda
environment, and ``pip`` in other cases.

Setting up conda
................

Wing can only use ``conda`` if your Anaconda base installation can be found.  See
`Package Management with conda <ref:packages/conda>`__ for details.

Setting up pipenv
.................

If you plan to use pipenv but it is not already set up, you can do so from the
``Options`` menu in the ``Packages`` tool, by first selecting ``Use pipenv`` and then
``Initialize for pipenv``. This installs pipenv into the Python you selected with
``Python Executable`` in Wing and then initializes the package manager directory to use
pipenv, which sets up a virtualenv and the initial pipenv configuration. 

Since this creates ``Pyfile`` and ``Pyfile.lock``, you will want to make sure that you
first save your Wing project in the directory you want to use as your pipenv project
directory, or set ``Project Home Directory`` under the ``Options`` tab in ``Project
Properties``.

Setting up Poetry
.................

If you plan to use Poetry but it is not already set up, you can do so from the
``Options`` menu in the ``Packages`` tool, by first selecting ``Use Poetry`` and then
``Initialize for Poetry``. This installs Poetry into the Python you selected with
``Python Executable`` in Wing and then initializes the package manager directory to use
Poetry, which sets up a virtualenv and the initial Poetry configuration. 

Since this creates ``pyproject.toml`` and ``poetry.lock``, you will want to make sure that
you first save your Wing project in the directory you want to use as your Poetry project
directory, or set ``Project Home Directory`` under the ``Options`` tab in ``Project
Properties``.

Setting up uv
.............

If you plan to use ``uv`` but it is not already set up, you can do so from the
``Options`` menu in the ``Packages`` tool, by first selecting ``Use uv`` and then
``Initialize for uv``. This installs ``uv`` if not already in your system and then initializes 
the project directory for use with ``uv``, which sets up a Python environment and the initial 
``uv`` configuration configuration. 

Since this creates ``pyproject.toml`` and ``uv.lock``, you will want to make sure that
you first save your Wing project in the directory you want to use as your ``uv`` project
directory, or set ``Project Home Directory`` under the ``Options`` tab in ``Project
Properties``.

Packages List
-------------

Once the package manager is configured, the ``Packages`` tool shows the current status
and list of installed packages.  

The status area at the top of the tool indicates the type of Python installation (whether
local or remote, and regular install or virtualenv), the package manager that is in use,
and the package configuration file that is being managed.

The packages tree below this is populated with the packages that are currently installed.  This
list indicates which packages are in use, either by the ``requirements.txt`` or ``Pipfile``
or by another installed and in-use package.  The version of the package currently installed
and the users of each package are listed at the end of each line.

Package management operations are available in the right-click context menu on the
packages list, and in the ``Options`` menu in the top right of the ``Packages`` tool.
These are described in detail in the next section.

Working with Containers and Clusters
------------------------------------

When working with containers or clusters, the ``Packages`` tool displays the packages
installed on your container and cluster but it does not offer any operations for
installing, removing, or updating packages.  In this case, the container or cluster
configuration must be edited manually and then rebuilt from the ``Containers`` tool.

