detect-installer

detect-installer is a zero-dependency Python library that figures out how a given package was installed, whether via pip, uv (project and pip modes), uv tool, pipx, Homebrew, Conda, or Mamba, and returns the correct upgrade command for that installer.

Call detect_installer("rich") and receive an InstallerInfo with the detected Installer enum and a ready-to-run upgrade_cmd string, or None if the package is not installed. It is published under the permissive 0BSD license so the single detection module can be vendored directly into a project.

What You Get

• A detect_installer() function returning an InstallerInfo dataclass
• An Installer enum covering pip, uv, uv-tool, pipx, brew, conda, and mamba
• The correct, installer-specific upgrade command as a ready-to-run string
• Zero runtime dependencies and a py.typed marker for full type hints
• A 0BSD license that permits copying the detection module directly into your project

Common Use Cases

• Showing users the right upgrade command in a CLI’s update notice
• Adapting self-update logic to pip, uv, pipx, Homebrew, or Conda
• Warning when a package was installed by an unexpected tool
• Vendoring a dependency-free installer-detection helper into a tool

Under The Hood

Architecture The library is a single detection module. _detect.py (~180 lines) defines the Installer enum, the frozen InstallerInfo dataclass, and the detect_installer() entry point. Detection combines two signals: the package’s importlib.metadata distribution (the INSTALLER file and direct-url metadata written at install time) and environment heuristics such as sys.prefix containing pipx/venvs or uv/tools, plus CONDA_PREFIX/MAMBA_EXE environment variables. Once the installer is identified, a per-installer branch formats the appropriate upgrade command. __init__.py re-exports the public names, and _test.py holds a small internal test helper.

Tech Stack Pure Python using only the standard library, importlib.metadata, dataclasses, enum, os, sys, and pathlib, with no third-party runtime dependencies. It targets modern Python with from __future__ import annotations and ships a py.typed marker for downstream type checking.

Code Quality The code is small, fully type-annotated, and uses a frozen dataclass and string-enum for a clear, immutable result type. Helper functions are individually documented and each detection path is isolated, making the heuristics easy to audit. The project is young with few commits, so real-world coverage across every installer edge case is still maturing.

API Design The surface is a single function returning a well-typed result: info = detect_installer("rich") yields info.installer (an Installer enum) and info.upgrade_cmd (a string), or None when the package is absent. This makes integration a two-line affair, and exposing the enum lets callers branch on the installer when they need custom behavior beyond the provided command.