Health Checks#

Conda doctor can be extended with the conda_health_checks plugin hook. Write new health checks using this hook, install the plugins you wrote, and they will run every time the conda doctor command is executed.

Basic Health Check#

A health check requires two components:

  • name: A human-readable name for the health check

  • action: A function that performs the check and prints results

Example of a basic health check:

from conda.plugins import hookimpl
from conda.plugins.types import CondaHealthCheck
from conda.base.constants import OK_MARK, X_MARK


def my_check(prefix: str, verbose: bool) -> None:
    """Check something in the environment."""
    if everything_ok(prefix):
        print(f"{OK_MARK} Everything looks good!")
    else:
        print(f"{X_MARK} Found a problem.")


@hookimpl
def conda_health_checks():
    yield CondaHealthCheck(
        name="My Custom Check",
        action=my_check,
    )

Health Checks with Fixes#

Health checks can optionally provide a fixer function that repairs detected issues. When a user runs conda doctor --fix, the fixer function is called after the check.

The fixer function receives:

  • prefix: The environment prefix path

  • args: The parsed command-line arguments (includes dry_run, yes, etc.)

It should return an integer exit code (0 for success).

Example with a fix:

from conda.plugins import hookimpl
from conda.plugins.types import CondaHealthCheck
from conda.base.constants import OK_MARK, X_MARK
from conda.base.context import context
from conda.reporters import confirm_yn


def my_check(prefix: str, verbose: bool) -> None:
    if is_broken(prefix):
        print(f"{X_MARK} Something is broken.")
    else:
        print(f"{OK_MARK} All good!")


def my_fix(prefix: str, args) -> int:
    if not is_broken(prefix):
        print("Nothing to fix.")
        return 0

    print("Found issue to fix.")
    confirm_yn("Proceed with fix?", dry_run=context.dry_run)

    # Perform the fix
    do_repair(prefix)
    print("Fixed!")
    return 0


@hookimpl
def conda_health_checks():
    yield CondaHealthCheck(
        name="My Fixable Check",
        action=my_check,
        fixer=my_fix,
        summary="Check for broken things",
        fix="Repair broken things",
    )

The confirm_yn function handles dry-run mode automatically by raising DryRunExit when context.dry_run is True.

API Reference#

class CondaHealthCheck#

Return type to use when defining conda health checks plugin hook.

Health checks are diagnostic actions that report on the state of a conda environment. They are invoked via conda doctor.

Health checks can optionally provide a fix capability, which is invoked via conda doctor --fix or conda doctor --fix <name>.

Fixer guidelines:

Fixers receive a confirm function that handles user confirmation and dry-run mode automatically. Simply call it with your message:

  • In normal mode: Prompts the user for confirmation (default: no).

  • In dry-run mode: Raises DryRunExit (handled by the framework).

  • If user declines: Raises CondaSystemExit (handled by the framework).

Example:

from conda.plugins.types import ConfirmCallback

def my_fixer(prefix: str, args: Namespace, confirm: ConfirmCallback) -> int:
    issues = find_issues(prefix)
    if not issues:
        print("No issues found.")
        return 0

    print(f"Found {len(issues)} issues")
    confirm("Fix these issues?")
    # ... perform fix ...
    return 0

For details on how this is used, see conda_health_checks().

Parameters:

  • name -- Health check identifier (e.g., missing-files).

  • action -- Callable that performs the check: action(prefix, verbose) -> None.

  • fixer -- Optional callable that fixes issues: fixer(prefix, args, confirm) -> int. The confirm parameter is a function to call for user confirmation. It raises an exception if the user declines or in dry-run mode.

  • summary -- Short description of what the check detects (shown in --list).

  • fix -- Short description of what the fix does (shown in --list).

action#
fix#
fixer#
name#
summary#
conda_health_checks()#

Register health checks for conda doctor.

This plugin hook allows you to add more "health checks" to conda doctor that you can write to diagnose problems in your conda environment. Check out the health checks already shipped with conda for inspiration.

Health checks can optionally provide a fixer callable that is invoked via conda doctor --fix or conda doctor --fix <check-name>.

Example (check only):

from conda import plugins


def example_health_check(prefix: str, verbose: bool):
    print("This is an example health check!")


@plugins.hookimpl
def conda_health_checks():
    yield plugins.types.CondaHealthCheck(
        name="example-health-check",
        action=example_health_check,
    )

Example (check with fix):

from conda import plugins


def my_health_check(prefix: str, verbose: bool):
    # Check and report issues
    print("Checking for issues...")


def my_health_fix(prefix: str, args) -> int:
    # Fix the issues
    print("Fixing issues...")
    return 0  # exit code


@plugins.hookimpl
def conda_health_checks():
    yield plugins.CondaHealthCheck(
        name="my-check",
        action=my_health_check,
        fixer=my_health_fix,
        summary="Check for common issues",
        fix="Repair detected issues",
    )
Returns:

An iterable of health check entries.