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

When `uv <https://docs.astral.sh/uv/>`__ is used for package management, Wing
runs ``uv`` command lines to implement the package operations.  

Configuring Python Executable
-----------------------------

When using ``uv``, the ``Python Executable`` in Wing's ``Propect Properties`` should be
set to the virtualenv created by uv. Wing checks the configuration and asks to correct
the ``Python Executable`` if necessary. If this is not done, Wing will debug and execute
your code in the wrong Python environment.

You may elect to correct ``Python Executable`` automatically without prompting. This is
done from the checkbox in the confirmation dialog or from the ``Options`` menu in the
``Packages`` tool.

Manual Configuration
....................

If you need to find uv's virtualenv manually, this can be done by executing the
following command line in the directory where your ``pyproject.toml`` and ``uv.lock`` 
are located::

  uv run python -c "import sys, os; print(os.path.dirname(sys.executable))"

Then set ``Python Executable`` to ``Activated Env`` and enter the *full path* to the
virtualenv's activation script. On Windows this is in ``Scripts\activate.bat`` below the
directory printed by the above command. On macOS and Linux, this is ``activate`` instead.

uv Auto-Install
---------------

If ``uv`` is the active package manager for a project, then Wing will ensure that ``uv`` is
installed first, using ``pipx``. If you don't have ``pipx`` then this will fail.

Removing the uv Virtualenv
--------------------------

If the virtualenv created by ``uv`` is removed by deleting the ``.venv`` directory, then Wing will
not be able to debug or execute code until the virtualenv is recreated, either with ``uv venv``.

.. note::

  **Important**: If you are working on a remote host, container, or cluster and remove
  the ``.venv`` directory, Wing will lose contact with the remote system because it uses the
  configured ``Python Executable`` to run its remote agent. In this case, you will need to
  manually recreate the virtualenv by running ``uv venv`` on the remote system,
  in the directory that contains your ``uv.lock``.
