jdx/mise · error

{reason}.\n\n{instructions}\n\nIf pipx is already installed,

Error message

{reason}.\n\n{instructions}\n\nIf pipx is already installed, verify it with `mise which pipx` and `pipx --version`.

What it means

Thrown by the pipx backend's `install_version_` when the `pipx` executable is required to install a Python-tool request but was not found on the system. mise shells out to an external pipx for these installs; without it there is no way to install the package, so mise fails with instructions on how to verify or install pipx.

Source

Thrown at src/backend/pipx.rs:378

            // below, so it cannot pass on evidence the spawn will then reject. On Windows a
            // `pipx.ps1` or a shebang-only `pipx.pyz` satisfies the plain lookup but cannot
            // be launched, and it used to reach `pipx install` and die with
            // "program not found" instead of these instructions.
            if !pipx_available {
                let pipx_configured = match self.dependency_toolset(&ctx.config).await {
                    Ok(ts) => ts.versions.keys().any(|ba| ba.short == "pipx"),
                    Err(_) => false,
                };
                let reason = if pipx_configured {
                    "pipx is configured but its executable was not found or is not runnable"
                        .to_string()
                } else {
                    format!(
                        "pipx is required to install {} but was not found",
                        self.ba()
                    )
                };
                bail!(
                    "{reason}.\n\n{instructions}\n\nIf pipx is already installed, verify it with `mise which pipx` and `pipx --version`."
                );
            }
        }

        let request = self.tool_name().parse::<PipxRequest>()?;

        if let Some(uv_program) = uv_program {
            let package_request = request.uvx_request(&tv.version, &options);
            self.warn_if_uv_may_not_support_exclude_newer(ctx).await;
            ctx.pr
                .set_message(format!("uv tool install {package_request}"));
            let mut cmd = Self::uvx_cmd(
                &uv_program,
                &ctx.config,
                &["tool", "install", &package_request],
                self,
                &tv,

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Install pipx and ensure it is on PATH: `pipx --version` to verify; `mise which pipx` to see what mise resolves.
2. Install pipx through mise itself: `mise use pipx@latest` (or `mise use -g pipx@latest`), then retry the tool install.
3. If using a custom executable, set the pipx `executable` option/`MISE_PIPX_EXECUTABLE`-style opt to the correct binary path.
4. In CI, add a step that provisions Python and pipx before running `mise install`.

Example fix

// before (mise.toml)
[tools]
"pipx:black" = "24.4.2"   // fails: no pipx on PATH

// after
[tools]
pipx = "latest"
"pipx:black" = "24.4.2"

# run before installing pipx-backed tools
command -v pipx >/dev/null 2>&1 && pipx --version || { echo 'pipx missing'; mise use -g pipx@latest; }

try { await $`mise install` } catch (e) { if (String(e).includes('pipx is required')) { await $`mise use -g pipx@latest`; await $`mise install`; } else throw e; }

When it happens

Trigger: Running `mise install`/`mise use pipx:<package>` (e.g. `pipx:ipython`) when `pipx` is absent from PATH, the `pipx_executable` option points to a nonexistent binary, or pipx exists only in an environment not active in the current shell.

Common situations: Fresh machine without pipx installed; pipx installed via `pip install --user` but `~/.local/bin` missing from PATH; using mise in CI where Python/pipx aren't provisioned; a configured custom executable path that moved after a Python upgrade.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• pipx was found during dependency validation but could not be
• pipx is required to install {} but was not found. {instruct
• the packslip gives no download URL for {}
• the packslip names an artifact {:?}, which is not a plain fi
• resolved pkgx package {name}@{version} does not satisfy {req

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/ea48aa3541bcd7c6. Report an issue: GitHub.