feat(commands): add clean command.

The new command supports selective cleanup with `--cache`, `--logs`,
`--trash`, and `--venvs` flags to remove specific components. Running
`pipx clean` without flags performs a full cleanup, removing all pipx
data and resetting to a fresh installation state.

Author: ever3001

changelog.d/1606.feature.md

@@ -0,0 +1,8 @@
+Add `pipx clean` command to remove pipx data.
+
+The new command supports selective cleanup with `--cache`, `--logs`,
+`--trash`, and `--venvs` flags to remove specific components. Running
+`pipx clean` without flags performs a full cleanup, removing all pipx
+data and resetting to a fresh installation state. All cleanup operations
+require user confirmation unless the `--force` flag is used. Use
+`--verbose` for detailed output including paths and progress information.

docs/examples.md

@@ -187,3 +187,51 @@ This example pins `pip` (temporarily, until the next automatic upgrade, if that
 ```shell
 > pipx upgrade-shared --pip-args=pip==24.0
 ```
+
+## `pipx clean` examples
+
+The `clean` command helps you free up disk space by removing pipx data. You can selectively clean specific components or perform a complete cleanup.
+
+### Clean specific components
+
+Remove only the cache (temporary virtual environments from `pipx run`):
+
+```
+pipx clean --cache
+```
+
+Remove only log files:
+
+```
+pipx clean --logs
+```
+
+Empty the trash directory:
+
+```
+pipx clean --trash
+```
+
+Remove all installed packages and their virtual environments:
+
+```
+pipx clean --venvs
+```
+
+### Clean multiple components
+
+You can combine flags to clean multiple components at once:
+
+```
+pipx clean --cache --logs --trash
+```
+
+### Full cleanup
+
+Remove **all** pipx data (this will uninstall all packages and reset pipx to a fresh state):
+
+```
+pipx clean
+```
+
+> ⚠️ **Warning**: Running `pipx clean` without any flags will remove ALL pipx data, including all installed packages. This operation requires confirmation unless the `--force` flag is used.

src/pipx/commands/__init__.py

@@ -1,3 +1,4 @@
+from pipx.commands.clean_cmd import clean
 from pipx.commands.ensure_path import ensure_pipx_paths
 from pipx.commands.environment import environment
 from pipx.commands.inject import inject
@@ -13,6 +14,7 @@
 from pipx.commands.upgrade import upgrade, upgrade_all, upgrade_shared
 
 __all__ = [
+    "clean",
     "ensure_pipx_paths",
     "environment",
     "inject",

src/pipx/commands/clean_cmd.py

@@ -0,0 +1,225 @@
+"""Clean command for pipx CLI."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pipx.colors import bold, red
+from pipx.constants import (
+    EXIT_CODE_CACHE_CLEANUP_FAIL,
+    EXIT_CODE_FULL_CLEANUP_FAIL,
+    EXIT_CODE_LOGS_CLEANUP_FAIL,
+    EXIT_CODE_OK,
+    EXIT_CODE_TRASH_CLEANUP_FAIL,
+    EXIT_CODE_VENVS_CLEANUP_FAIL,
+    ExitCode,
+)
+from pipx.emojis import hazard, stars
+from pipx.paths import ctx
+from pipx.util import rmdir
+from pipx.venv import VenvContainer
+
+
+def _cleanup_directory(
+    path: Path,
+    description: str,
+    error_code: ExitCode,
+    verbose: bool,
+) -> ExitCode:
+    """
+    Remove a directory with standardized error handling and output.
+
+    Args:
+        path: Directory path to remove
+        description: User-friendly description of what's being removed
+        error_code: Exit code to return on failure
+        verbose: Whether to print detailed output
+
+    Returns:
+        EXIT_CODE_OK on success, error_code on failure
+    """
+    if not path.exists():
+        if verbose:
+            print(f"Skipping {description} (directory doesn't exist)")
+        return EXIT_CODE_OK
+
+    action = f"Removing {description}..."
+    if verbose:
+        print(f"{action}")
+        print(f"  Path: {path}")
+    else:
+        print(bold(action))
+
+    try:
+        rmdir(path, safe_rm=False)
+    except Exception as e:
+        print(f"{red(f'Error removing {description}:')} {e}")
+        return error_code
+
+    print(f"{stars} {description.capitalize()} removed.")
+    return EXIT_CODE_OK
+
+
+def _confirm_action(message: str) -> bool:
+    """
+    Prompt user for confirmation.
+
+    Args:
+        message: Question to ask the user
+
+    Returns:
+        True if user confirms, False otherwise
+    """
+    while True:
+        response = input(f"{message} [y/N]: ").lower().strip()
+        if response in ("y", "yes"):
+            return True
+        if response in ("n", "no", ""):
+            return False
+        print("Please answer 'y' or 'n'")
+
+
+def _full_cleanup(verbose: bool) -> ExitCode:
+    """
+    Remove all pipx data, resetting to first installation state.
+
+    This is the nuclear option - removes everything including:
+    - All installed packages (venvs)
+    - Cache and temporary data
+    - Logs
+    - Trash
+    - Shared libraries
+
+    Args:
+        verbose: Print detailed output
+        force: Skip confirmation prompt
+    """
+    print(f"{hazard}  {red('WARNING')}: This will remove ALL pipx data!")
+    print(red("All installed packages will be lost."))
+    print()
+
+    return _cleanup_directory(
+        path=ctx.home,
+        description="all pipx data",
+        error_code=EXIT_CODE_FULL_CLEANUP_FAIL,
+        verbose=verbose,
+    )
+
+
+def _cache_cleanup(verbose: bool) -> ExitCode:
+    """Remove cached virtual environments from 'pipx run' commands."""
+    return _cleanup_directory(
+        path=ctx.venv_cache,
+        description="cache and temporary data",
+        error_code=EXIT_CODE_CACHE_CLEANUP_FAIL,
+        verbose=verbose,
+    )
+
+
+def _logs_cleanup(verbose: bool) -> ExitCode:
+    """Remove pipx log files."""
+    return _cleanup_directory(
+        path=ctx.logs,
+        description="logs",
+        error_code=EXIT_CODE_LOGS_CLEANUP_FAIL,
+        verbose=verbose,
+    )
+
+
+def _trash_cleanup(verbose: bool) -> ExitCode:
+    """Remove files in the trash directory."""
+    return _cleanup_directory(
+        path=ctx.trash,
+        description="trash",
+        error_code=EXIT_CODE_TRASH_CLEANUP_FAIL,
+        verbose=verbose,
+    )
+
+
+def _venvs_cleanup(verbose: bool) -> ExitCode:
+    """Remove all installed packages and their virtual environments."""
+    venv_container = VenvContainer(ctx.venvs)
+    venv_dirs = list(venv_container.iter_venv_dirs())
+
+    if not venv_dirs:
+        if verbose:
+            print("No installed packages to remove.")
+        return EXIT_CODE_OK
+
+    print(bold(f"Removing {len(venv_dirs)} installed package(s)..."))
+
+    failed = []
+    for venv_dir in venv_dirs:
+        package_name = venv_dir.name
+        try:
+            if verbose:
+                print(f"  Removing {package_name}...")
+            rmdir(venv_dir, safe_rm=False)
+        except Exception as e:
+            failed.append((package_name, e))
+            if verbose:
+                print(f"    {red('Failed')}: {e}")
+
+    if failed:
+        print(f"{red(f'Failed to remove {len(failed)} package(s):')}")
+        for package_name, error in failed:
+            print(f"  - {package_name}: {error}")
+        return EXIT_CODE_VENVS_CLEANUP_FAIL
+
+    print(f"{stars} All installed packages removed.")
+    return EXIT_CODE_OK
+
+
+def clean(
+    cache: bool = False,
+    logs: bool = False,
+    trash: bool = False,
+    venvs: bool = False,
+    verbose: bool = False,
+    force: bool = False,
+) -> ExitCode:
+    """
+    Clean pipx data directories.
+
+    If no specific options are provided, performs a full cleanup removing
+    all pipx data. Otherwise, removes only the specified components.
+
+    Args:
+        cache: Remove cache and temporary virtual environments
+        logs: Remove log files
+        trash: Empty trash directory
+        venvs: Remove all installed packages
+        verbose: Print detailed output including paths and progress
+
+    Returns:
+        Combined exit code (0 if all succeeded, non-zero if any failed)
+    """
+    if not force:
+        if not _confirm_action("Are you sure you want to continue?"):
+            print("Operation cancelled.")
+            return EXIT_CODE_OK
+    # Determine what to clean
+    any_selected = cache or logs or trash or venvs
+
+    if not any_selected:
+        # No specific options: full cleanup
+        return _full_cleanup(verbose)
+
+    # Selective cleanup: run requested operations
+    cleanup_operations = []
+    if cache:
+        cleanup_operations.append(_cache_cleanup)
+    if logs:
+        cleanup_operations.append(_logs_cleanup)
+    if trash:
+        cleanup_operations.append(_trash_cleanup)
+    if venvs:
+        cleanup_operations.append(_venvs_cleanup)
+
+    # Execute all operations and combine exit codes
+    exit_code = EXIT_CODE_OK
+    for operation in cleanup_operations:
+        result = operation(verbose)
+        exit_code |= result
+
+    return exit_code

src/pipx/constants.py

@@ -23,6 +23,11 @@
 EXIT_CODE_REINSTALL_VENV_NONEXISTENT = ExitCode(1)
 EXIT_CODE_REINSTALL_INVALID_PYTHON = ExitCode(1)
 EXIT_CODE_SPECIFIED_PYTHON_EXECUTABLE_NOT_FOUND = ExitCode(1)
+EXIT_CODE_FULL_CLEANUP_FAIL = ExitCode(1)
+EXIT_CODE_CACHE_CLEANUP_FAIL = ExitCode(1)
+EXIT_CODE_LOGS_CLEANUP_FAIL = ExitCode(1)
+EXIT_CODE_TRASH_CLEANUP_FAIL = ExitCode(1)
+EXIT_CODE_VENVS_CLEANUP_FAIL = ExitCode(1)
 
 
 def is_windows() -> bool:

src/pipx/main.py

@@ -408,6 +408,15 @@ def run_pipx_command(args: argparse.Namespace, subparsers: Dict[str, argparse.Ar
             skip=skip_list,
             python_flag_passed=python_flag_passed,
         )
+    elif args.command == "clean":
+        return commands.clean(
+            cache=args.cache,
+            logs=args.logs,
+            trash=args.trash,
+            venvs=args.venvs,
+            verbose=verbose,
+            force=args.force,
+        )
     elif args.command == "runpip":
         if not venv_dir:
             raise PipxError("Developer error: venv_dir is not defined.")
@@ -733,6 +742,56 @@ def _add_reinstall(subparsers, venv_completer: VenvCompleter, shared_parser: arg
     p.add_argument("package").completer = venv_completer
     add_python_options(p)
 
+def _add_clean(
+    subparsers: argparse._SubParsersAction, 
+    shared_parser: argparse.ArgumentParser
+) -> None:
+    """Add the clean command to the parser."""
+    p = subparsers.add_parser(
+        "clean",
+        help="Completely reset pipx to first installation state",
+        description=textwrap.dedent(
+            f"""
+            Removes all installed packages, temporary virtual environments,
+            and cached data, effectively resetting pipx to its initial state.
+            The granularity of the cleanup can be controlled using the following options:
+            --venvs : Remove all installed packages and their virtual environments.
+            --logs  : Remove all pipx log files.
+            --trash : Empty the pipx trash directory.
+            --cache : Remove cached data and temporary virtual environments, leaving installed packages intact.
+            """
+        ),
+        parents=[shared_parser],
+    )
+    p.add_argument(
+        "--cache",
+        action="store_true",
+        help="Remove cached data and temporary virtual environments, leaving installed packages intact",
+    )
+    p.add_argument(
+        "--logs",
+        action="store_true",
+        help="Remove all pipx log files",
+    )
+    p.add_argument(
+        "--trash",
+        action="store_true",
+        help="Empty the pipx trash directory",
+    )
+    p.add_argument(
+        "--venvs",
+        action="store_true",
+        help="Remove all installed packages and their virtual environments",
+    )
+    p.add_argument(
+        "--force",
+        "-f",
+        action="store_true",
+        help="Skip confirmation prompts (use with caution!)",
+    )
+    p.set_defaults(subparser=p)
+
+
 
 def _add_reinstall_all(subparsers: argparse._SubParsersAction, shared_parser: argparse.ArgumentParser) -> None:
     p = subparsers.add_parser(
@@ -994,6 +1053,7 @@ def get_command_parser() -> Tuple[argparse.ArgumentParser, Dict[str, argparse.Ar
     _add_uninstall_all(subparsers, shared_parser)
     _add_reinstall(subparsers, completer_venvs.use, shared_parser)
     _add_reinstall_all(subparsers, shared_parser)
+    _add_clean(subparsers, shared_parser)
     _add_list(subparsers, shared_parser)
     subparsers_with_subcommands["interpreter"] = _add_interpreter(subparsers, shared_parser)
     _add_run(subparsers, shared_parser)