semantic options (`with`, `expose`, and…

Error message

{} semantic options (`with`, `expose`, and `dependency_prereleases`) require uv; install uv and ensure uvx is enabled

What it means

install_version_ bails when the tool's options use uv-only semantic features (with, expose, dependency_prereleases) but no uv/uvx executable could be resolved as a spawnable dependency at install time. These options are implemented via uv, so uv must be installed and uvx enabled.

Solutions

Install uv with `mise use uv@latest` (or add uv to your toolset)
Ensure uvx is enabled (don't set uvx = false in the tool options)
Alternatively remove the with/expose/dependency_prereleases options and rely on plain pipx

Example fix

// before (mise.toml)
[tools]
"pipx:ruff" = { version = "latest", with = ["rich"] }
// after
[tools]
uv = "latest"
"pipx:ruff" = { version = "latest", with = ["rich"] }

Defensive patterns

Strategy: fallback

Validate before calling

// ensure uv is present before installing tools with uv-only options
const ok = await isInstalled("uv") || (await $`mise exec uv -- uv --version`.exitCode === 0);
if (!ok) throw new Error("install uv: mise use uv@latest");

Try / catch

try { await $`mise install pipx:ruff` } catch (e) {
  if (/require uv/.test(e.message)) await $`mise use uv@latest`, await $`mise install pipx:ruff`;
  else throw e;
}

Prevention

Add uv to your base toolset whenever any pipx tool uses with/expose/dependency_prereleases
Check `mise which uv` in CI setup steps before running mise install

When it happens

Trigger: Installing a pipx tool whose options contain with/expose/dependency_prereleases while `uv` is neither installed (not in the toolset nor on PATH) nor spawnable, even if uvx is nominally enabled in config.

Common situations: Fresh machine where `mise use pipx@...` config includes `with` options but uv was never added to the toolset; CI images that install only pipx; user previously installed uv via another manager that is no longer on PATH.

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

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

Appendix: source

Thrown at src/backend/pipx.rs:555

        let options = PipxOptions::new(&request_options);

        // Check if pipx is available (unless uvx is being used)
        //
        // Asks for a *spawnable* uv, because this both picks the branch and supplies the
        // program `uvx_cmd` hands to `CmdLineRunner`. A `uv.ps1` or a shebang-only `uv`
        // satisfies the plain lookup, so mise would commit to the uv branch and then fail
        // at process creation; treating it as absent falls through to pipx, which either
        // works or reports the install instructions below. The branch only changes in the
        // case where the branch it would have taken cannot run.
        let uvx_allowed = Settings::get().pypi.uvx != Some(false) && !options.uvx_disabled();
        let uv_program = if uvx_allowed {
            self.spawnable_dependency(&ctx.config, Some(&ctx.ts), "uv")
                .await
        } else {
            None
        };
        if options.has_uv_only_options()? && uv_program.is_none() {
            bail!(
                "{} semantic options (`with`, `expose`, and `dependency_prereleases`) require uv; install uv and ensure uvx is enabled",
                self.ba.short
            );
        }
        let pipx_available = if uv_program.is_none() {
            self.spawnable_dependency(&ctx.config, Some(&ctx.ts), "pipx")
                .await
                .is_some()
        } else {
            false
        };

        if uv_program.is_none() {
            // Only offer uv as an alternative when this package can actually use it.
            // Packages that set `uvx = false` (or a `pipx.uvx = false` setting) always go
            // through pipx, so pointing at uv there just sends people down a dead end.
            let instructions = if uvx_allowed {
                "To use pipx packages with mise, you need to install pipx first:\n  \

View on GitHub (pinned to 533346cc37)