Metadata-Version: 2.4
Name: venvcleaner
Version: 0.2.0
Summary: A TUI/GUI tool for cleaning up Python virtual environments (venv directories).
License-Expression: MIT
License-File: LICENSE
Author: yamakox
Author-email: notolog.tech@gmail.com
Requires-Python: >=3.10
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Provides-Extra: gui
Requires-Dist: click (>=8.3.0)
Requires-Dist: python-dotenv (>=1.2.3)
Requires-Dist: textual (>=3.0.0)
Requires-Dist: wxpython (>=4.2.1) ; extra == "gui"
Project-URL: Homepage, https://github.com/yamakox/VenvCleaner
Project-URL: Issues, https://github.com/yamakox/VenvCleaner/issues
Project-URL: Repository, https://github.com/yamakox/VenvCleaner.git
Description-Content-Type: text/markdown

# 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](https://docs.astral.sh/uv/guides/tools/):

```bash
uvx venvcleaner
```

![TUI mode](https://raw.githubusercontent.com/yamakox/VenvCleaner/main/tui-mode.png)

You can also run in **GUI mode**:

```bash
uvx --with wxpython venvcleaner
```

![GUI mode](https://raw.githubusercontent.com/yamakox/VenvCleaner/main/gui-mode.png)

You can specify a target directory:

```bash
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](https://wxpython.org/blog/2017-08-17-builds-for-linux-with-pip/) and [wxWidgets for GTK installation](https://docs.wxwidgets.org/3.2/plat_gtk_install.html).

Alternatively, on [some Linux systems](https://wxpython.org/pages/downloads/index.html), you can use the `-f` (`--find-links`) option to specify [the download URL of wxPython package](https://extras.wxpython.org/wxPython4/extras/linux/):

```bash
# 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:

```bash
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:

```bash
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:

```bash
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

|Key|Action|
|---|---|
|`↑` / `↓`|Move within the venv list|
|`Space`|Toggle selection of the current row|
|`Tab` / `Shift+Tab`|Move focus between widgets|
|`Enter`|Activate the focused button / confirm path input|
|`a`|Select All|
|`n`|Select None|
|`r`|Refresh|
|`d`|Dump Paths|
|`Esc` / `q`|Quit|

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:

```text
~/.config/venvcleaner/.env
```

|Variable|Description|
|---|---|
|`TEXTUAL_THEME`|Textual theme name (for example `textual-light`, `textual-dark`, or `ansi-dark`). If unset or empty, the Textual default theme is used.|

Example:

```bash
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](https://raw.githubusercontent.com/yamakox/VenvCleaner/main/LICENSE).

