Package Management with uv

Classic+

When 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 Project 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 (the ⋯ button) 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.

Environments Without pip

Environments created by uv venv or uv sync have no pip. When the project's environment has no pip, the Packages tool runs uv pip in its place and shows using uv pip in its status line. This works for any environment without pip, including one with no uv.lock.

If uv is not found, the Packages tool says so. Install uv and then select Rescan for Package Manager from the Options menu, or select Install pip into Environment there to add pip to the environment.

Code that runs pip by name in such an environment gets the next pip on the PATH, which installs into another Python. Use uv pip there 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.

When the New Project dialog creates a uv environment and uv is not installed, Wing can install it with pip install --user or pipx install uv. See Creating Python Environments for details.

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 by running uv sync in the directory that contains your uv.lock.

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 sync on the remote system, in the directory that contains your uv.lock.

Related Documents

« 5.4. Package Management with Poetry
Table of Contents
5.6. Package Management Security »