pyfirstaid 0.2.3__tar.gz → 0.4.0__tar.gz

{pyfirstaid-0.2.3 → pyfirstaid-0.4.0}/.github/workflows/ci.yml

@@ -13,6 +13,14 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+        # Python 3.9 is end-of-life and not built for ubuntu-latest (26.04),
+        # so test it on Ubuntu 24.04 instead.
+        exclude:
+          - os: ubuntu-latest
+            python-version: "3.9"
+        include:
+          - os: ubuntu-24.04
+            python-version: "3.9"
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5

{pyfirstaid-0.2.3 → pyfirstaid-0.4.0}/.github/workflows/publish.yml

@@ -8,7 +8,7 @@ on:
       tag:
         description: "Release tag to attach pyfirstaid.pyz to"
         required: true
-        default: "v0.1.0"
+        default: "v0.4.0"
 
 jobs:
   publish:

{pyfirstaid-0.2.3 → pyfirstaid-0.4.0}/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.4.0
+
+Four new checks for the tools people use to manage Pythons and projects. Like the conda
+check, they only read files on disk and run no uv, Poetry, pyenv or Jupyter commands.
+
+- **New `jupyter` check**: Jupyter kernels whose Python no longer exists (deleted venv,
+  upgraded Python), an environment that has ipykernel but is not registered as a kernel,
+  and several kernels with the same name in the kernel picker.
+- **New `uv` check**: a uv project whose `.venv` was never created, is broken (its base
+  Python is gone), or is not the Python running. Also respects `UV_PROJECT_ENVIRONMENT`.
+- **New `poetry` check**: finds the project's Poetry environment (in-project `.venv` or
+  Poetry's cache folder), and warns when it is broken or not the Python running.
+- **New `pyenv` check**: a `.python-version` file (or `PYENV_VERSION`) asking for a different
+  Python than the one running, a pinned version pyenv hasn't installed, and pyenv not set
+  up in the shell. uv reads `.python-version` too, so this also helps uv users.
+- `pip-mismatch`: in an environment made by uv (which has no pip by design), it now
+  suggests `uv pip install` instead of reporting pip as missing.
+- Report: checks for tools you don't use are shown on one line ("Not used here: ...").
+  Multi-line fixes are indented properly.
+
+## 0.3.0
+
+- **New `conda` check** for problems from mixing conda and pip (something `conda doctor`
+  doesn't look at):
+  - a package conda installed that pip later replaced, so both tools think they own it,
+  - pip packages installed into the conda *base* environment,
+  - a conda environment that is activated, but isn't the Python actually running.
+  It only reads files on disk, runs no conda or pip commands, and stays quiet when unsure.
+- README: up-to-date example output; author link on PyPI.
+
 ## 0.2.3
 
 - Clearer PEP 668 message: it now says the block can come from your OS *or* a package

{pyfirstaid-0.2.3 → pyfirstaid-0.4.0}/PKG-INFO

@@ -1,15 +1,16 @@
 Metadata-Version: 2.5
 Name: pyfirstaid
-Version: 0.2.3
+Version: 0.4.0
 Summary: First aid for broken Python environments: finds what's wrong and tells you how to fix it.
 Project-URL: Homepage, https://github.com/sai-sakalam/pyfirstaid
 Project-URL: Source, https://github.com/sai-sakalam/pyfirstaid
 Project-URL: Issues, https://github.com/sai-sakalam/pyfirstaid/issues
 Project-URL: Changelog, https://github.com/sai-sakalam/pyfirstaid/blob/main/CHANGELOG.md
+Project-URL: Author, https://sai-sakalam.github.io/
 Author: Sai Gavaskar Sakalam
 License-Expression: MIT
 License-File: LICENSE
-Keywords: diagnostics,environment,pip,ssl,troubleshooting,venv,virtualenv
+Keywords: conda,diagnostics,environment,jupyter,pip,poetry,pyenv,ssl,troubleshooting,uv,venv,virtualenv
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -32,14 +33,14 @@ Description-Content-Type: text/markdown
 
 # pyfirstaid 🩹
 [![PyPI](https://img.shields.io/pypi/v/pyfirstaid)](https://pypi.org/project/pyfirstaid/)
-[![Python versions](https://img.shields.io/pypi/pyversions/pyfirstaid)](https://pypi.org/project/pyfirstaid/)
-[![Downloads](https://static.pepy.tech/badge/pyfirstaid/month)](https://pepy.tech/projects/pyfirstaid)
+[![Python versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/pyfirstaid/)
 [![CI](https://github.com/sai-sakalam/pyfirstaid/actions/workflows/ci.yml/badge.svg)](https://github.com/sai-sakalam/pyfirstaid/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/sai-sakalam/pyfirstaid/blob/main/LICENSE)
+[![XERJ Corpus Hub contributor](https://hub.xerj.org/contributors/sai-sakalam/badge.svg)](https://hub.xerj.org/contributors/sai-sakalam)
 
 **First aid for broken Python environments.** One command tells you *what's broken* and *exactly how to fix it*.
 
-> **Status: early, actively developed.** 12 checks, tested on Windows, macOS and Linux (Python 3.9–3.14).
+> **Status: early, actively developed.** 17 checks, tested on Windows, macOS and Linux (Python 3.9–3.14).
 > Feedback is very welcome in [Issues](https://github.com/sai-sakalam/pyfirstaid/issues). *Which problems do you hit most?*
 
 ---
@@ -60,7 +61,7 @@ system Python, and a file called `random.py` is hiding the real `random` module:
 ```console
 $ python -m pyfirstaid --share
 
-pyfirstaid 0.2.0: checking your Python environment
+pyfirstaid 0.4.0: checking your Python environment
 Python 3.13.1 (~/project/.venv/bin/python)
 
 ✔ Python 3.13.1 (supported until October 2029)
@@ -83,6 +84,7 @@ Python 3.13.1 (~/project/.venv/bin/python)
 ✔ No dependency conflicts (pip check)
 ✔ site-packages is writable
 ✔ Default text encoding is UTF-8
+- Not used here: conda, uv, poetry, pyenv, jupyter
 
 1 problem(s), 2 warning(s).
 ```
@@ -162,6 +164,24 @@ Shows which Python `python` / `python3` actually start, warns about Apple's buil
 
 Tells you whether you're installing into a read-only system Python (use a venv or pipx) or into a venv that was created with `sudo`.
 
+**"I installed a package, but my Jupyter notebook still says `ModuleNotFoundError`."**
+
+    python -m pyfirstaid --only jupyter,pip-mismatch
+
+The notebook runs a *kernel*, and the kernel may use a different Python than your terminal. pyfirstaid finds kernels that point at a deleted or moved Python, and tells you when your environment isn't registered as a kernel at all. Tip: inside a notebook, use `%pip install <package>` (not `!pip install`), so it installs into the kernel's Python.
+
+**"It works with `uv run` / `poetry run`, but not when I run `python` myself."**
+
+    python -m pyfirstaid --only uv,poetry,venv
+
+The project's packages live in its own environment. pyfirstaid tells you whether the Python running is that environment, whether it exists yet (`uv sync` / `poetry install`), or whether it broke after a Python upgrade.
+
+**"pyenv says one version, but `python --version` shows another."**
+
+    python -m pyfirstaid --only pyenv,path
+
+Compares the Python running with your `.python-version` file (or `PYENV_VERSION`), and tells you if the version isn't installed in pyenv or pyenv isn't set up in your shell.
+
 **"pip check shows conflicts and I don't know what to install."**
 
     python -m pyfirstaid --only dependencies
@@ -204,7 +224,12 @@ Download `pyfirstaid.pyz` from the [latest release](https://github.com/sai-sakal
 |---|---|
 | `python-version` | Python past (or close to) end of life, pre-release Pythons, Apple's built-in Command Line Tools Python |
 | `venv` | No venv active, an unused `.venv` in the folder, a *different* venv activated in your shell, a system Python that blocks pip (PEP 668) |
-| `pip-mismatch` | `pip` installs into a different Python than the one you run, pip missing, a broken `pip` command |
+| `conda` | A package conda installed that pip later replaced, pip packages in the conda *base* environment, a conda environment that is activated but isn't the Python running |
+| `uv` | A uv project whose environment isn't created yet, is broken (its base Python is gone), or isn't the Python running |
+| `poetry` | A Poetry project whose environment is missing, broken, or isn't the Python running |
+| `pyenv` | `.python-version` / `PYENV_VERSION` asking for a different Python than the one running, a version pyenv hasn't installed, pyenv not set up in your shell |
+| `jupyter` | Kernels pointing to a Python that no longer exists, an environment with ipykernel that isn't registered as a kernel, kernels with the same name |
+| `pip-mismatch` | `pip` installs into a different Python than the one you run, pip missing (with the `uv pip` fix in uv environments), a broken `pip` command |
 | `path` | Typing `python` / `python3` runs a *different* Python, or the Windows Microsoft Store shortcut |
 | `leaks` | `PYTHONPATH` / `PYTHONHOME` set, venvs that can see system packages |
 | `shadowing` | Files like `random.py` or `requests.py` in your folder that hide real modules |
@@ -222,7 +247,7 @@ Run one or a few: `python -m pyfirstaid --only shadowing,path`. List them all: `
 | Tool | What it does | Gap pyfirstaid fills |
 |---|---|---|
 | `pip check` | Finds dependency conflicts | Only covers one kind of problem |
-| `conda doctor` | Health checks for conda environments | Doesn't cover pip, venv or uv |
+| `conda doctor` | Health checks for conda environments | Doesn't check what pip did inside conda, or venv / uv |
 | pymedic | Lists environment info (versions, packages) | Reports, but doesn't diagnose or suggest fixes |
 | pyenv-doctor | Early-stage environment checks | Single release so far |
 | env-repair | Repairs conda and pip environments | Changes your environment; pyfirstaid only diagnoses, safely |
@@ -240,8 +265,8 @@ Run one or a few: `python -m pyfirstaid --only shadowing,path`. List them all: `
 
 ## Scope
 
-**In:** pip, venv and uv on Windows, macOS and Linux.
-**Out (for now):** conda (use `conda doctor`), Poetry and pyenv specifics, automatic repair.
+**In:** pip, venv and uv on Windows, macOS and Linux, plus conda / pip mixing problems.
+**Out (for now):** conda's own internals (use `conda doctor`), Poetry and pyenv specifics, automatic repair.
 
 ## Contributing
 
@@ -249,6 +274,10 @@ Run one or a few: `python -m pyfirstaid --only shadowing,path`. List them all: `
 - Development: `python -m pip install -e ".[dev]"`, then `python -m pytest` and `ruff check src tests`.
 - A new check is one file in `src/pyfirstaid/checks/` that returns a list of `Finding`s, registered in `checks/__init__.py`.
 
+## Author
+
+Made by [Sai Sakalam](https://sai-sakalam.github.io/), a data engineer who kept fixing the same broken Python environments for colleagues and decided to automate it. Feedback and ideas are always welcome.
+
 ## License
 
 MIT

{pyfirstaid-0.2.3 → pyfirstaid-0.4.0}/README.md

@@ -1,13 +1,13 @@
 # pyfirstaid 🩹
 [![PyPI](https://img.shields.io/pypi/v/pyfirstaid)](https://pypi.org/project/pyfirstaid/)
-[![Python versions](https://img.shields.io/pypi/pyversions/pyfirstaid)](https://pypi.org/project/pyfirstaid/)
-[![Downloads](https://static.pepy.tech/badge/pyfirstaid/month)](https://pepy.tech/projects/pyfirstaid)
+[![Python versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/pyfirstaid/)
 [![CI](https://github.com/sai-sakalam/pyfirstaid/actions/workflows/ci.yml/badge.svg)](https://github.com/sai-sakalam/pyfirstaid/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/sai-sakalam/pyfirstaid/blob/main/LICENSE)
+[![XERJ Corpus Hub contributor](https://hub.xerj.org/contributors/sai-sakalam/badge.svg)](https://hub.xerj.org/contributors/sai-sakalam)
 
 **First aid for broken Python environments.** One command tells you *what's broken* and *exactly how to fix it*.
 
-> **Status: early, actively developed.** 12 checks, tested on Windows, macOS and Linux (Python 3.9–3.14).
+> **Status: early, actively developed.** 17 checks, tested on Windows, macOS and Linux (Python 3.9–3.14).
 > Feedback is very welcome in [Issues](https://github.com/sai-sakalam/pyfirstaid/issues). *Which problems do you hit most?*
 
 ---
@@ -28,7 +28,7 @@ system Python, and a file called `random.py` is hiding the real `random` module:
 ```console
 $ python -m pyfirstaid --share
 
-pyfirstaid 0.2.0: checking your Python environment
+pyfirstaid 0.4.0: checking your Python environment
 Python 3.13.1 (~/project/.venv/bin/python)
 
 ✔ Python 3.13.1 (supported until October 2029)
@@ -51,6 +51,7 @@ Python 3.13.1 (~/project/.venv/bin/python)
 ✔ No dependency conflicts (pip check)
 ✔ site-packages is writable
 ✔ Default text encoding is UTF-8
+- Not used here: conda, uv, poetry, pyenv, jupyter
 
 1 problem(s), 2 warning(s).
 ```
@@ -130,6 +131,24 @@ Shows which Python `python` / `python3` actually start, warns about Apple's buil
 
 Tells you whether you're installing into a read-only system Python (use a venv or pipx) or into a venv that was created with `sudo`.
 
+**"I installed a package, but my Jupyter notebook still says `ModuleNotFoundError`."**
+
+    python -m pyfirstaid --only jupyter,pip-mismatch
+
+The notebook runs a *kernel*, and the kernel may use a different Python than your terminal. pyfirstaid finds kernels that point at a deleted or moved Python, and tells you when your environment isn't registered as a kernel at all. Tip: inside a notebook, use `%pip install <package>` (not `!pip install`), so it installs into the kernel's Python.
+
+**"It works with `uv run` / `poetry run`, but not when I run `python` myself."**
+
+    python -m pyfirstaid --only uv,poetry,venv
+
+The project's packages live in its own environment. pyfirstaid tells you whether the Python running is that environment, whether it exists yet (`uv sync` / `poetry install`), or whether it broke after a Python upgrade.
+
+**"pyenv says one version, but `python --version` shows another."**
+
+    python -m pyfirstaid --only pyenv,path
+
+Compares the Python running with your `.python-version` file (or `PYENV_VERSION`), and tells you if the version isn't installed in pyenv or pyenv isn't set up in your shell.
+
 **"pip check shows conflicts and I don't know what to install."**
 
     python -m pyfirstaid --only dependencies
@@ -172,7 +191,12 @@ Download `pyfirstaid.pyz` from the [latest release](https://github.com/sai-sakal
 |---|---|
 | `python-version` | Python past (or close to) end of life, pre-release Pythons, Apple's built-in Command Line Tools Python |
 | `venv` | No venv active, an unused `.venv` in the folder, a *different* venv activated in your shell, a system Python that blocks pip (PEP 668) |
-| `pip-mismatch` | `pip` installs into a different Python than the one you run, pip missing, a broken `pip` command |
+| `conda` | A package conda installed that pip later replaced, pip packages in the conda *base* environment, a conda environment that is activated but isn't the Python running |
+| `uv` | A uv project whose environment isn't created yet, is broken (its base Python is gone), or isn't the Python running |
+| `poetry` | A Poetry project whose environment is missing, broken, or isn't the Python running |
+| `pyenv` | `.python-version` / `PYENV_VERSION` asking for a different Python than the one running, a version pyenv hasn't installed, pyenv not set up in your shell |
+| `jupyter` | Kernels pointing to a Python that no longer exists, an environment with ipykernel that isn't registered as a kernel, kernels with the same name |
+| `pip-mismatch` | `pip` installs into a different Python than the one you run, pip missing (with the `uv pip` fix in uv environments), a broken `pip` command |
 | `path` | Typing `python` / `python3` runs a *different* Python, or the Windows Microsoft Store shortcut |
 | `leaks` | `PYTHONPATH` / `PYTHONHOME` set, venvs that can see system packages |
 | `shadowing` | Files like `random.py` or `requests.py` in your folder that hide real modules |
@@ -190,7 +214,7 @@ Run one or a few: `python -m pyfirstaid --only shadowing,path`. List them all: `
 | Tool | What it does | Gap pyfirstaid fills |
 |---|---|---|
 | `pip check` | Finds dependency conflicts | Only covers one kind of problem |
-| `conda doctor` | Health checks for conda environments | Doesn't cover pip, venv or uv |
+| `conda doctor` | Health checks for conda environments | Doesn't check what pip did inside conda, or venv / uv |
 | pymedic | Lists environment info (versions, packages) | Reports, but doesn't diagnose or suggest fixes |
 | pyenv-doctor | Early-stage environment checks | Single release so far |
 | env-repair | Repairs conda and pip environments | Changes your environment; pyfirstaid only diagnoses, safely |
@@ -208,8 +232,8 @@ Run one or a few: `python -m pyfirstaid --only shadowing,path`. List them all: `
 
 ## Scope
 
-**In:** pip, venv and uv on Windows, macOS and Linux.
-**Out (for now):** conda (use `conda doctor`), Poetry and pyenv specifics, automatic repair.
+**In:** pip, venv and uv on Windows, macOS and Linux, plus conda / pip mixing problems.
+**Out (for now):** conda's own internals (use `conda doctor`), Poetry and pyenv specifics, automatic repair.
 
 ## Contributing
 
@@ -217,6 +241,10 @@ Run one or a few: `python -m pyfirstaid --only shadowing,path`. List them all: `
 - Development: `python -m pip install -e ".[dev]"`, then `python -m pytest` and `ruff check src tests`.
 - A new check is one file in `src/pyfirstaid/checks/` that returns a list of `Finding`s, registered in `checks/__init__.py`.
 
+## Author
+
+Made by [Sai Sakalam](https://sai-sakalam.github.io/), a data engineer who kept fixing the same broken Python environments for colleagues and decided to automate it. Feedback and ideas are always welcome.
+
 ## License
 
 MIT

{pyfirstaid-0.2.3 → pyfirstaid-0.4.0}/pyproject.toml

@@ -11,7 +11,8 @@ license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.9"
 authors = [{ name = "Sai Gavaskar Sakalam" }]
-keywords = ["pip", "virtualenv", "venv", "diagnostics", "troubleshooting", "ssl", "environment"]
+keywords = ["pip", "virtualenv", "venv", "diagnostics", "troubleshooting", "ssl", "environment",
+            "conda", "uv", "poetry", "pyenv", "jupyter"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Environment :: Console",
@@ -41,6 +42,7 @@ Homepage = "https://github.com/sai-sakalam/pyfirstaid"
 Source = "https://github.com/sai-sakalam/pyfirstaid"
 Issues = "https://github.com/sai-sakalam/pyfirstaid/issues"
 Changelog = "https://github.com/sai-sakalam/pyfirstaid/blob/main/CHANGELOG.md"
+Author = "https://sai-sakalam.github.io/"
 
 [tool.hatch.version]
 path = "src/pyfirstaid/__init__.py"

{pyfirstaid-0.2.3 → pyfirstaid-0.4.0}/src/pyfirstaid/__init__.py

@@ -1,3 +1,3 @@
 """pyfirstaid: first aid for broken Python environments."""
 
-__version__ = "0.2.3"
+__version__ = "0.4.0"

{pyfirstaid-0.2.3 → pyfirstaid-0.4.0}/src/pyfirstaid/checks/__init__.py

@@ -7,15 +7,20 @@ from typing import List
 from pyfirstaid.checks import (
     broken_installs,
     compiled,
+    conda,
     dependencies,
     encoding,
+    jupyter,
     leaks,
     path_check,
     permissions,
     pip_mismatch,
+    poetry,
+    pyenv,
     python_version,
     shadowing,
     ssl_check,
+    uv,
     venv,
 )
 from pyfirstaid.model import Check
@@ -23,6 +28,11 @@ from pyfirstaid.model import Check
 ALL_CHECKS: List[Check] = [
     Check(python_version.CHECK_ID, "Python version", python_version.run_check),
     Check(venv.CHECK_ID, "Virtual environment", venv.run_check),
+    Check(conda.CHECK_ID, "conda / pip mixing", conda.run_check),
+    Check(uv.CHECK_ID, "uv project environment", uv.run_check),
+    Check(poetry.CHECK_ID, "Poetry project environment", poetry.run_check),
+    Check(pyenv.CHECK_ID, "pyenv / .python-version", pyenv.run_check),
+    Check(jupyter.CHECK_ID, "Jupyter kernels", jupyter.run_check),
     Check(pip_mismatch.CHECK_ID, "pip / python match", pip_mismatch.run_check),
     Check(path_check.CHECK_ID, "python on PATH", path_check.run_check),
     Check(leaks.CHECK_ID, "PYTHONPATH / PYTHONHOME", leaks.run_check),

pyfirstaid-0.4.0/src/pyfirstaid/checks/conda.py

@@ -0,0 +1,166 @@
+"""Check: problems from mixing conda and pip in a conda environment.
+
+`conda doctor` checks conda's own files but not what pip did to the environment.
+This check looks only at files on disk (no conda or pip commands are run):
+
+- a package that conda installed and pip later replaced (two tools fighting over it),
+- packages pip-installed into the conda *base* environment,
+- a conda environment that is activated but is not the Python actually running.
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import os
+import re
+import sys
+from typing import Dict, List, Optional, Set
+
+from pyfirstaid.model import Finding, Options, Status
+from pyfirstaid.util import norm, site_package_dirs
+
+CHECK_ID = "conda"
+
+_META_RE = re.compile(r"^(?P<name>.+?)-(?P<ver>[^-]+)\.(?:dist-info|egg-info)$")
+
+
+def normalize(name: str) -> str:
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def is_conda_env(prefix: str) -> bool:
+    """Every conda environment (base included) has a conda-meta folder."""
+    return os.path.isdir(os.path.join(prefix, "conda-meta"))
+
+
+def is_base_env(prefix: str) -> bool:
+    """The base environment holds conda itself: it has condabin/ or an envs/ folder."""
+    return (os.path.isdir(os.path.join(prefix, "condabin"))
+            or os.path.isdir(os.path.join(prefix, "envs")))
+
+
+def conda_records(prefix: str) -> Dict[str, Set[str]]:
+    """Map normalized conda package name -> metadata folder names conda installed for it.
+
+    Reads conda-meta/*.json. The set is empty for packages that ship no Python metadata.
+    """
+    records: Dict[str, Set[str]] = {}
+    for path in glob.glob(os.path.join(prefix, "conda-meta", "*.json")):
+        try:
+            with open(path, encoding="utf-8") as fh:
+                data = json.load(fh)
+        except (OSError, ValueError):
+            continue
+        name = data.get("name")
+        if not isinstance(name, str):
+            continue
+        metas: Set[str] = set()
+        for f in data.get("files") or []:
+            if not isinstance(f, str):
+                continue
+            for part in f.replace("\\", "/").split("/"):
+                if part.endswith((".dist-info", ".egg-info")):
+                    metas.add(part)
+                    break
+        records.setdefault(normalize(name), set()).update(metas)
+    return records
+
+
+def installer_of(meta_dir: str) -> str:
+    try:
+        with open(os.path.join(meta_dir, "INSTALLER"), encoding="utf-8") as fh:
+            return fh.read().strip().lower()
+    except OSError:
+        return ""
+
+
+def find_problems(site_dirs: List[str], records: Dict[str, Set[str]]):
+    """Return (replaced, pip_only): package names pip replaced over conda, and pip-only ones."""
+    owned_by_conda: Set[str] = set()
+    for metas in records.values():
+        owned_by_conda.update(metas)
+
+    replaced: List[str] = []
+    pip_only: List[str] = []
+    for d in site_dirs:
+        try:
+            entries = os.listdir(d)
+        except OSError:
+            continue
+        for entry in entries:
+            m = _META_RE.match(entry)
+            if not m or entry in owned_by_conda:
+                continue
+            if installer_of(os.path.join(d, entry)) != "pip":
+                continue  # conservative: only packages pip clearly says it installed
+            name = normalize(m.group("name"))
+            if name in records:
+                replaced.append("%s %s" % (name, m.group("ver")))
+            else:
+                pip_only.append(name)
+    return sorted(set(replaced)), sorted(set(pip_only))
+
+
+def run_check(opts: Options, prefix: Optional[str] = None,
+              site_dirs: Optional[List[str]] = None) -> List[Finding]:
+    prefix = prefix or sys.prefix
+    findings: List[Finding] = []
+    active = os.environ.get("CONDA_PREFIX")
+
+    if not is_conda_env(prefix):
+        if active and is_conda_env(active):
+            findings.append(Finding(
+                CHECK_ID, Status.WARN,
+                "A conda environment is activated, but this Python is not from it",
+                detail="activated: %s\nrunning:   %s" % (active, sys.executable),
+                fix="Use the environment's own Python: python -m pyfirstaid after "
+                    "`conda activate <env>`, or check which python with `which python` "
+                    "(Windows: `where python`).",
+            ))
+            return findings
+        return [Finding(CHECK_ID, Status.SKIP, "Not a conda environment")]
+
+    records = conda_records(prefix)
+    replaced, pip_only = find_problems(
+        site_dirs if site_dirs is not None else site_package_dirs(), records)
+    base = is_base_env(prefix)
+    env_hint = "the base environment" if base else "this conda environment"
+
+    if replaced:
+        findings.append(Finding(
+            CHECK_ID, Status.WARN,
+            "%d package(s) installed by conda were later replaced by pip" % len(replaced),
+            detail="conda and pip now both think they own these, which can cause "
+                   "import errors and broken updates:\n" + "\n".join(replaced[:8])
+                   + ("\n...and %d more" % (len(replaced) - 8) if len(replaced) > 8 else ""),
+            fix="Pick one tool per package. Usually: conda install --force-reinstall <name>. "
+                "Rule of thumb: install with conda first, and use pip only for packages "
+                "conda doesn't have.",
+        ))
+
+    if base and pip_only:
+        findings.append(Finding(
+            CHECK_ID, Status.WARN,
+            "%d package(s) pip-installed into the conda base environment" % len(pip_only),
+            detail="The base environment runs conda itself; extra pip packages there can "
+                   "break conda updates:\n" + ", ".join(pip_only[:10])
+                   + (" ..." if len(pip_only) > 10 else ""),
+            fix="Create a separate environment for your work: conda create -n myenv python, "
+                "then conda activate myenv",
+        ))
+
+    if active and norm(active) != norm(prefix):
+        findings.append(Finding(
+            CHECK_ID, Status.WARN,
+            "Your shell activated a DIFFERENT conda environment",
+            detail="activated: %s\nrunning:   %s" % (active, prefix),
+            fix="Run `conda activate <the env you meant>`, then run pyfirstaid again.",
+        ))
+
+    if not findings:
+        findings.append(Finding(
+            CHECK_ID, Status.OK,
+            "No conda / pip conflicts in %s" % env_hint,
+        ))
+    return findings