Venv Cleaner

A simple TUI/GUI tool for cleaning up old or unused Python virtual environments (venv directories).

How to Use

The easiest way to run in TUI mode is using uvx:

uvx venvcleaner

You can also run in GUI mode:

uvx --with wxpython venvcleaner

You can specify a target directory:

uvx venvcleaner /path/to/target-directory

TUI or GUI?

Venv Cleaner chooses the UI as follows:

• GUI mode when wxPython is installed, --no-gui is not set, and a display is available.
• TUI mode otherwise (including when you pass --no-gui).

On Linux, if both DISPLAY and WAYLAND_DISPLAY are unset (typical for SSH sessions without display forwarding), Venv Cleaner runs in TUI mode even when wxPython is installed. You can also force TUI mode with --no-gui on any platform.

Using GUI mode on Linux

If you want to use GUI mode on Linux, you will need to build wxPython via pip. Please see Building wxPython for Linux via Pip and wxWidgets for GTK installation.

Alternatively, on some Linux systems, you can use the -f (--find-links) option to specify the download URL of wxPython package:

# for Ubuntu 24.04
uvx -f https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-24.04 \
    --with wxpython==4.2.5 venvcleaner

Installing into a Persistent Environment

If you want to install Venv Cleaner into a persistent environment:

uv tool install "venvcleaner[gui]@latest"

# for Ubuntu 24.04
uv tool install -f https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-24.04 \
    --with wxpython==4.2.5 venvcleaner@latest

# run Venv Cleaner (GUI when available, otherwise TUI)
venvcleaner

# force TUI mode
venvcleaner --no-gui

Features

• Scans the target directory recursively for virtual environments (directories containing a pyvenv.cfg file).
• In TUI mode, you can change the target directory by editing the path field and pressing Enter, or refresh the scan with the Refresh button.
• In GUI mode, you can change or refresh the target directory with the Select... or Refresh buttons.
• Choose which venvs to clean using the selection list.
  • Select All selects all detected venvs.
  • Select None clears the selection.
  • In TUI mode, press Space to toggle the current row. In GUI mode, use the multi-select list.
• Copy Paths (GUI) copies the paths of selected venvs to your clipboard. You can paste them into a terminal to run shell commands manually. For example:

ls /path/to/project-1/.venv "/path/to/project 2/.venv"
rm -r /path/to/project-1/.venv "/path/to/project 2/.venv"

• Dump Paths (TUI) prints the full paths of selected venvs to stdout, one per line, and exits. This is useful on SSH or other remote sessions where clipboard access is unavailable. For example:

venvcleaner --no-gui /path/to/scan  # select venvs, then press Dump Paths
# /path/to/project-1/.venv
# /path/to/project-2/.venv

• Cleanup Venvs deletes the selected venv directories. In TUI mode, cleanup progress is briefly printed to the terminal, then the TUI resumes.

TUI Key Bindings

In modal dialogs, press Esc to close, or use the buttons. Click a column header to sort the list.

Environment Variables

TUI mode reads optional settings from:

~/.config/venvcleaner/.env

Example:

mkdir -p ~/.config/venvcleaner
echo 'TEXTUAL_THEME=textual-light' > ~/.config/venvcleaner/.env

You can also set TEXTUAL_THEME in your shell environment. Existing environment variables take precedence over values in .env.

License

This software is distributed under the terms of the MIT License.