<type>documentation</type>
<domain>packages</domain>
<id>operations</id>
<title>Package Management Operations</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>pro+</product>

Wing supports installing, removing, updating or downgrading packages, and also several
operations aimed at keeping the package configuration files up to date or making sure
that the packages specified in the configuration are installed.

.. note::

  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.

Installing Packages
-------------------

There are couple of ways to install packages with Wing's ``Packages`` tool:

**Install New Packages** in the ``Options`` menu can be used to find packages by typing
a name fragment, selecting those packages, and then installing them.

**Install Missing Packages** in the ``Options`` menu can be used to install all the packages
specified in the ``requirements.txt``, ``Pipfile``, or ``pyproject.toml``. This is useful when first
setting up a project on a new machine or after editing those files manually to add packages. 

When using ``pyproject.toml`` that is not synchronized with the packages lock file, you will need to
``Update Pipfile.lock``, ``Update poetry.lock``, or ``Update uv.lock`` from the ``Options`` menu
first before ``Install Missing Packages`` will work. 

When using ``uv``, ``Install Missing Packages`` also removes any unused packages, since ``uv``
does not separately install or remove packages when updating the set of installed packages
accoring to the ``uv.lock`` file.

.. 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 with any package manager!
  
Upgrading/Downgrading Packages
------------------------------

The version of packages that are installed can be changed in the following ways:

**Update Selected Packages** in the ``Options`` menu and package list's right-click
context menu updates packages to the latest available version.

**Set Package Version** in the ``Options`` menu and packages list's right-click context
menu may be used to specify a particular version to use for a package.

Removing Packages
-----------------

Packages may be removed as follows:

**Remove Selected Packages** in the ``Options`` menu and package list's right-click context menu
uninstalls packages.

**Remove Unused Packages** in the ``Options`` menu removes all unused packages, including only those
that are not listed in the package configuration file and not used by any package that is in use.
WHen using ``uv`` this also installs any missing packages, since ``uv`` does not distinguish between
removing or adding packages relative to the package specification in ``uv.lock``.

Note that except when using ``uv`` or ``poetry`` you cannot remove ``pip`` itself, or the packages
that it depends on, without entirely breaking package management. If this is needed, it should be
done outside of Wing. The ``Packages`` tool will cease to function and may be removed from the UI by
right-clicking on its tab.

When using ``pipenv``, it is possible to remove the package ``pipenv``, after which only ``pip``
can be used for package management from Wing. However, if ``pipenv`` is again selected as the
package manager in the ``Packages`` tool's ``Options`` menu or by auto-detecting a ``Pipfile`` in a
project, then Wing will auto-install ``pipenv`` again. See *Pipenv Auto-Install* in `Package
Management with pipenv <ref:packages/pipenv>`__ for details.

Other Operations
----------------

**Initialize requirements.txt**, **Initialize for Poetry**, **Initialize for pipenv**, and
**Initialize for uv** are shown in the ``Options`` menu when Wing detects that the package manager
has not been configured. When using ``pip`` this creates a ``requirements.txt`` with ``pip freeze``.
When using ``pipenv``, this installs ``pipenv`` and initializes the project directory as a
``pipenv`` project directory. When using Poetry, this installs ``poetry`` and initializes the
project directory as a Poetry project directory, by writing ``pyproject.toml`` and ``poetry.lock``.
When using ``uv`` this installs ``uv`` and initializes the ``uv`` project directory by writing
``pyproject.toml`` and ``uv.lock``. See `Package Manager <ref:packages/intro>`__ for details.

**Show Selected in PyPI** in the ``Options`` menu and the package list's right-click context menu
displays the `Python Package Index <https://pypi.org/>`__ (PyPI) page for the selected packages.

**Freeze to requirements.txt**, **Export to environment.yml**, **Update Pipfile.lock**, **Update
poetry.lock**, and **Update uv.lock** (for pip, conda, pipenv, Poetry, and uv, respectively) can be
used to produce a complete specification of the currently installed package set, including the
version for every package. This replaces any existing contents in these package configuration files.
When using pip, it retains package order from the existing ``requirements.txt`` but adds in any
missing packages and fills in versions for all packages.

**Refresh** in the package list's right-click context menu updates the installed packages list based
on the current state. This should only be needed if package operations are invoked outside of Wing.

Managing Configuration Files
----------------------------

When using ``pip`` or ``conda``, Wing manages any existing ``requirements.txt`` file by adding,
removing, or updating packages in it. This can be disabled by unchecking ``Auto-update
requirements.txt`` in the ``Options`` menu in Wing's ``Packages`` tool.

When using ``pipenv`` these operations update ``Pipfile`` and ``Pipfile.lock``. Additionally, Wing
may edit the ``Pipfile`` to make it possible to upgrade packages to the latest version, by removing
an older version specifier.

When using Poetry, all these operations update ``pyproject.toml`` and ``poetry.lock`` as if using
``poetry`` from the command line.

Similarly, when using ``uv``, these operations update ``pyproject.toml`` and ``uv.lock`` as if using
``uv`` from the command line.