@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/working-with-mise/references/dev-tools/backends/packslip-html.md

@@ -0,0 +1,310 @@
+Packslip Backend
+
+Packslip Backend [​](#packslip-backend)
+
+The [Packslip](https://packslip.dev) backend installs tools using signed release manifests published by their maintainers. mise verifies the release, selects the build for your platform, and installs its executables. Releases can also include shell completions and agent skills.
+
+Packslip is the preferred [Tier 1 backend](https://mise.jdx.dev/registry.html#backends) for tools whose publishers provide these manifests. For other tools, use [aqua](https://mise.jdx.dev/dev-tools/backends/aqua.html), [GitHub](https://mise.jdx.dev/dev-tools/backends/github.html), or another supported backend. You do not need to install the Packslip CLI.
+
+For the background and examples of version-matched completions and agent skills, read [Introducing packslip](https://jdx.dev/posts/2026-09-05-introducing-packslip/).
+
+## Quick start [​](#usage)
+
+Install [hk](https://hk.jdx.dev), a git hook and lint manager, in your project:
+
+sh
+
+```
+mise use packslip:github.com/jdx/hk
+mise exec -- hk --version
+```
+
+This records hk in the project's `mise.toml`. The equivalent configuration is:
+
+toml
+
+```
+[tools]
+"packslip:github.com/jdx/hk" = "latest"
+```
+
+Run `mise install` after adding that configuration manually. To make hk available outside a project, use `mise use -g packslip:github.com/jdx/hk`. The registry shorthand `mise use hk` also selects Packslip by default.
+
+## Supported project identifiers [​](#project-names-and-discovery)
+
+Use `packslip:` followed by the project's host and path, without `https://`. For GitHub, you can omit the host: `packslip:jdx/hk` is equivalent to `packslip:github.com/jdx/hk`.
+
+| Identifier | Source |
+| --- | --- |
+| `packslip:github.com/owner/repo` | A GitHub repository's releases. |
+| `packslip:github.com/owner/repo/tools/mytool` | One tool in a GitHub monorepo. |
+| `packslip:tool.example.com` | A signed release list hosted by the publisher. |
+| `packslip:example.com/tools/mytool` | One tool on a publisher's domain. |
+
+The project must publish Packslip manifests; this backend does not infer installation instructions from arbitrary release filenames. GitHub projects have built-in release discovery and signer identity rules. Other hosts need a signed release list and an explicit [signer configuration](#pubkey).
+
+For bundle filenames, discovery URLs, and monorepo identity rules, see [project discovery](https://mise.jdx.dev/dev-tools/packslip-verification.html#project-discovery).
+
+### Private GitHub repositories [​](#private-repositories)
+
+A private repository works with the same credentials the [`github:` backend](https://mise.jdx.dev/dev-tools/github-tokens.html) uses — `MISE_GITHUB_TOKEN`, `GITHUB_API_TOKEN`, or `GITHUB_TOKEN` — and needs nothing in your configuration:
+
+mise.toml
+
+toml
+
+```
+[tools]
+"packslip:github.com/my-org/internal-cli" = "latest"
+```
+
+GitHub serves release assets of a private repository only from its API, not from the `github.com/.../releases/download/...` URLs a manifest records, so mise retries there with your token when a download fails. The token is used for transport only: the signature, project identity, signer continuity, and artifact digest checks are unchanged, and no credential is read from the signed manifest.
+
+## Versions [​](#versions)
+
+List available versions or select a specific release:
+
+sh
+
+```
+mise ls-remote packslip:github.com/jdx/hk
+mise use packslip:github.com/jdx/hk@1.58.1
+```
+
+Only releases with Packslip manifests are available through this backend. The registry shorthand selects Aqua for hk versions before 1.58.1, so `mise use hk@1.57.0` continues to work. You can also select Aqua explicitly with `mise use aqua:jdx/hk@VERSION`.
+
+Packslip uses semantic versions, including compatible date versions such as `2026.9.1`. Prereleases are excluded unless you enable the [`prerelease`](#prerelease) tool option. mise also applies [`minimum_release_age`](https://mise.jdx.dev/configuration/settings.html#minimum_release_age), which defaults to 24 hours. A recently published release may therefore be absent from the list until it reaches that age.
+
+### How `latest` is selected [​](#latest)
+
+`latest` follows the publisher's recommendation when it is eligible:
+
+1. The publisher's `latest` pointer in a signed release list.
+2. GitHub's latest release, if there is no signed pointer.
+3. The highest eligible semantic version, if there is no eligible recommendation.
+
+A publisher can recommend an older supported release even when a newer major version exists. Prefix and channel requests keep their normal matching rules. Every candidate must satisfy the configured verification and installation policies.
+
+Offline, version listing and `latest` use cached results, or return no versions if the cache is empty. Installation still performs verification. See [version resolution](https://mise.jdx.dev/dev-tools/packslip-verification.html#version-resolution) for signed lists, withdrawals, and fallback behavior.
+
+### Reproduce an installation [​](#reproduce-an-installation)
+
+A `latest` request can resolve differently after the publisher recommends a new release. Keep the request in `mise.toml` and commit a generated lockfile when your team needs to install the same version:
+
+sh
+
+```
+mise install
+git add mise.toml mise.lock
+```
+
+The first installation records the version, signer, and artifact commitments in `mise.lock`; commit that file with `mise.toml`. Teammates and CI can then enforce those commitments after checking out the project:
+
+sh
+
+```
+mise install --locked
+```
+
+`mise lock` can resolve the Packslip version without installing it, but it cannot record the selected artifact's commitments before the first installation. Installation still needs the artifacts or usable cached copies and must satisfy current verification policy. See [mise.lock](https://mise.jdx.dev/dev-tools/mise-lock.html) for target platforms and updates.
+
+## Completions and skills [​](#completions)
+
+With [mise activated](https://mise.jdx.dev/getting-started.html#activate-mise), installing hk also makes its completions available:
+
+sh
+
+```
+mise use packslip:github.com/jdx/hk
+```
+
+Type `hk` and press Tab. mise loads the completion script declared by hk's release and follows the hk version active in each project. No separate completion installation or `usage` dependency is needed. Bash, zsh, fish, and PowerShell are supported. See [Packslip completions](https://mise.jdx.dev/dev-tools/packslip-resources.html#completions) for details and manual setup without shell activation.
+
+Tools can also publish agent skills. Use `mise skills ls` to see the skills provided by active tools and `mise skills sync --dir .agents/skills` to link them into your agent's directory. A tool must declare a skill for it to appear.
+
+See [Packslip completions and skills](https://mise.jdx.dev/dev-tools/packslip-resources.html) for setup, automatic skill synchronization, and when resource generation runs a publisher's executable.
+
+## Verification [​](#what-is-verified)
+
+mise verifies the publisher's signature, the requested project and version, and the selected download's digest and size before unpacking it. The signer must match the expected repository identity or your configured public key. mise also checks any existing signer pin, lockfile commitments, and applicable release-age or stamper policy.
+
+A **manifest** describes the release. A **bundle** contains the manifest and its signature evidence. An **artifact** is a downloadable build named by the manifest. mise retains the verified manifest as `.mise-packslip.json` in the install directory.
+
+Verification authenticates the publisher and downloaded bytes. It does not establish that the software is safe. mise records whether build provenance links are present, but does not fetch and verify that linked provenance. See [verification details](https://mise.jdx.dev/dev-tools/packslip-verification.html#verification-checks).
+
+### Signer changes [​](#pinned-signers)
+
+mise remembers previously accepted signers in its local state. [`mise.lock`](https://mise.jdx.dev/dev-tools/mise-lock.html) can also record the project's signer and artifact checksums, carrying those commitments to another machine.
+
+If a release changes signer, inspect the remembered identity:
+
+sh
+
+```
+mise packslip pins
+mise packslip pins --json
+```
+
+After confirming the publisher's announced signing-key or workflow change, reset the local pin for that project:
+
+sh
+
+```
+mise packslip forget github.com/jdx/hk
+```
+
+This also resets the remembered vendor release-list continuity. It does **not** change explicit signer options, erase stamper-list state, or remove a signer commitment from `mise.lock`. Configure the new signer policy first; if a lockfile entry conflicts, remove that entry and regenerate it with `mise install`. Review and commit the resulting lockfile change. See [signer continuity](https://mise.jdx.dev/dev-tools/packslip-verification.html#signer-continuity) for the changes that require this review.
+
+## Tool options [​](#tool-options)
+
+These [tool options](https://mise.jdx.dev/dev-tools/#tool-options) apply to one entry in `[tools]`. The settings `packslip.exec`, `packslip.stampers`, and `skills.*` belong under `[settings]` instead.
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| [`variant`](#variant) | No variant | Select a publisher-declared alternative build. |
+| [`pubkey`](#pubkey) | Unset | Pin a minisign-format public key or public-key file. |
+| [`identity`, `identity_prefix`, `issuer`](#identity-identity-prefix-issuer) | Derived from a recognized forge | Set the expected keyless signer and OIDC issuer. |
+| [`list_identity_prefix`](#list-identity-prefix) | Release signer policy | Pin a different workflow for the vendor release list. |
+| [`prerelease`](#prerelease) | `false` | Include prerelease versions. |
+| [`trust`](#trust) | Apply configured stampers | Use `"vendor"` to exempt this tool from stamp requirements. |
+| [`allow_unlogged`](#allow-unlogged) | `false` | Accept key-signed bundles without transparency-log evidence. |
+| [`ignore_requirements`](#ignore-requirements) | `false` | Install despite confirmed host requirement failures. |
+
+### `variant` [​](#variant)
+
+Select a named alternative build, such as `fips` or `baseline`. Without this option, mise considers only artifacts with no variant. The publisher must provide the requested variant.
+
+toml
+
+```
+[tools]
+"packslip:github.com/example/tool" = { version = "latest", variant = "fips" }
+```
+
+### `pubkey` [​](#pubkey)
+
+For a key-signed project, obtain the publisher's public key through a trusted channel. Set `pubkey` to the minisign-format public-key line or the path to its `.pub` file. The release list and bundles must verify against that key.
+
+toml
+
+```
+[tools]
+"packslip:tool.example.com" = { version = "latest", pubkey = "/path/to/vendor.pub" }
+```
+
+### `identity`, `identity_prefix`, `issuer` [​](#identity-identity-prefix-issuer)
+
+For keyless signing, specify an exact certificate `identity` or an `identity_prefix`, plus its OIDC `issuer`. These options override the policy derived from the forge name. Keep the trailing slash in a repository prefix. For example, a domain project signed by a GitHub workflow could use:
+
+toml
+
+```
+[tools]
+"packslip:tool.example.com" = { version = "latest", identity_prefix = "https://github.com/example/tool/", issuer = "https://token.actions.githubusercontent.com" }
+```
+
+Replace the example identity with the publisher's verified identity. Recognizing the signing issuer does not add release discovery: the domain still needs a [signed release list](https://mise.jdx.dev/dev-tools/packslip-verification.html#project-discovery).
+
+### `list_identity_prefix` [​](#list-identity-prefix)
+
+When a different workflow signs the vendor's release list, pin its certificate identity prefix separately. It replaces `identity` and `identity_prefix` only for the vendor's list; release bundles still require their original signer. The OIDC `issuer` is shared (including an issuer derived from a forge project). Without this option, the list uses the same policy as release bundles.
+
+The value must be a non-empty string and requires an issuer. It cannot be combined with `pubkey`. It does not affect configured stampers, whose lists use their own pins.
+
+### `prerelease` [​](#prerelease)
+
+Include prereleases when listing or selecting versions:
+
+toml
+
+```
+[tools]
+"packslip:github.com/jdx/hk" = { version = "latest", prerelease = true }
+```
+
+### `trust` [​](#trust)
+
+Use `trust = "vendor"` to exempt one tool from configured [stampers](#stamps). Vendor signature verification still applies, and mise records this choice in the lockfile options.
+
+toml
+
+```
+[tools]
+"packslip:github.com/jdx/hk" = { version = "latest", trust = "vendor" }
+```
+
+### `allow_unlogged` [​](#allow-unlogged)
+
+Set to `true` only when your policy accepts key-signed bundles without transparency-log evidence. Signature and artifact verification still apply.
+
+### `ignore_requirements` [​](#ignore-requirements)
+
+Set to `true` to install despite confirmed [host requirement](#host-requirements) failures. This does not supply missing libraries or make an incompatible executable run. It also bypasses the glibc-to-musl fallback, retaining the GNU artifact selected for the host. Other verification checks still apply.
+
+## Advanced policies [​](#advanced-policies)
+
+### Signed release lists [​](#signed-release-lists)
+
+Publishers can use signed lists to recommend or withdraw versions and provide bundle locations. For domain projects, a list is required; for GitHub, it supplements release discovery. See [signed release lists](https://mise.jdx.dev/dev-tools/packslip-verification.html#signed-release-lists).
+
+Accepted lists must remain available and current. See [list continuity and release age](https://mise.jdx.dev/dev-tools/packslip-verification.html#release-list-continuity-and-minimum-age) for expiry, rollback protection, and timestamp checks.
+
+### Stamps [​](#stamps)
+
+Stampers are services you configure to approve releases in addition to the publisher's signature. No stamps are required by default. See [stamper configuration and mirrors](https://mise.jdx.dev/dev-tools/packslip-verification.html#stamps).
+
+### Artifact selection and host requirements [​](#artifact-selection)
+
+mise selects a build using the signed OS, architecture, libc, and variant metadata, then checks its declared host requirements. When a GNU build's declared `glibc_min` is newer than the host, mise selects a matching static musl build when one is available. Setting `ignore_requirements = true` bypasses this fallback and keeps the GNU artifact selected. An ambiguous build or another confirmed incompatibility can prevent installation. See [artifact selection](https://mise.jdx.dev/dev-tools/packslip-verification.html#artifact-selection) and [host requirements](https://mise.jdx.dev/dev-tools/packslip-verification.html#host-requirements).
+
+## Troubleshooting [​](#troubleshooting)
+
+Start with debug output for the failing command, for example:
+
+sh
+
+```
+MISE_DEBUG=1 mise install packslip:github.com/jdx/hk
+```
+
+| Symptom | Next step |
+| --- | --- |
+| No versions or bundle found | Check the project identifier and `mise ls-remote`. Confirm that the release has a Packslip manifest and is old enough for `minimum_release_age`. The publisher must supply missing manifests. |
+| Nothing pins the signer | Configure `pubkey`, or a certificate identity/prefix and issuer, using details confirmed with the publisher. |
+| Signer change or trust downgrade refused | Inspect `mise packslip pins`, explicit tool options, and `mise.lock`. Follow [signer changes](#pinned-signers) after confirming the publisher's change. |
+| No eligible artifact | Check your platform and requested variant. The publisher must provide a matching build. |
+| Ambiguous artifacts | The publisher must distinguish the builds in the manifest; changing local options cannot fix identical metadata. |
+| Host requirements failed | Install the reported dependency or use a compatible host. See [host requirements](#host-requirements) before overriding a failure. |
+| Signed list expired, rolled back, or missing | Ask the list's publisher for a current valid list. Removing an accepted list does not reset its policy. |
+| Version excluded by stamp policy | Check your configured stampers. A trusted stamper must approve the version, and the vendor must not have withdrawn it. |
+| Digest or size mismatch | Report the affected release and artifact to the publisher; the download must match the signed manifest. |
+| 404 on a private repository's release | Confirm the token in `MISE_GITHUB_TOKEN`, `GITHUB_API_TOKEN`, or `GITHUB_TOKEN` can read the repository. See [private repositories](#private-repositories). |
+
+For completion and skill errors, see [resource troubleshooting](https://mise.jdx.dev/dev-tools/packslip-resources.html#troubleshooting).
+
+## Publishing tools for mise [​](#why-publish-one)
+
+A Packslip manifest lets mise install your releases without a new registry shorthand or a separate filename-matching recipe. You can keep your existing release layout and add versioned completions, CLI specifications, or agent skills.
+
+To support mise:
+
+1. Publish installable artifacts with accurate platform metadata and executable paths.
+2. Sign a manifest containing their digests and publish its bundle with the release.
+3. For domain hosting, publish a signed release list and tell users how to pin your signer.
+4. Optionally declare [completions and skills](https://mise.jdx.dev/dev-tools/packslip-resources.html).
+
+For GitHub Actions, follow the [Packslip publishing guide](https://packslip.dev/docs/publishing/) for the action version, permissions, inputs, and monorepo setup. Run the action after building and uploading the final artifacts. For domain hosting, see [signed release lists](https://packslip.dev/docs/release-lists/).
+
+The [Packslip specification](https://packslip.dev/release/v1/) defines the format. For mise's implementation details, see [`src/backend/packslip.rs`](https://github.com/jdx/mise/blob/main/src/backend/packslip.rs).
+
+[Edit this page](https://github.com/jdx/mise/edit/main/docs/dev-tools/backends/packslip.md)
+
+Last updated:
+
+Pager
+
+[Previous pagenpm](https://mise.jdx.dev/dev-tools/backends/npm.html)
+
+[Next pagepypi](https://mise.jdx.dev/dev-tools/backends/pypi.html)
+
+MIT License·Copyright © 2026· [![](https://github.com/jdx.png?size=96)jdx.dev](https://jdx.dev)

package/skills/working-with-mise/references/dev-tools/backends/pipx-html.md

@@ -0,0 +1,329 @@
+PyPI Backend
+
+PyPI Backend [​](#pypi-backend)
+
+The `pypi` backend installs Python command-line applications in isolated virtual environments. Each tool gets its own dependencies. Use a project environment and pip or uv for application libraries such as NumPy and requests.
+
+## Quick start [​](#dependencies)
+
+Install uv, Python, and a CLI from PyPI:
+
+sh
+
+```
+mise use python@3.14 uv pypi:black
+mise exec -- black --version
+```
+
+### Project configuration [​](#usage)
+
+This adds the following to `mise.toml`:
+
+toml
+
+```
+[tools]
+python = "3.14"
+uv = "latest"
+"pypi:black" = "latest"
+```
+
+Add `-g` to `mise use` to install tools globally.
+
+mise uses uv to install tools. With [dependency locking](#dependency-locking), it runs `uv sync --frozen`; version-only installs use `uv tool install`. If uv is unavailable, version-only installs fall back to `pipx install`. See [Using pipx](#using-pipx) to select that installer explicitly.
+
+## Package sources [​](#supported-pipx-syntax)
+
+Use `pypi:black` for the PyPI distribution or `pypi:psf/black` for its GitHub source. Their releases and installation requirements can differ.
+
+| Source | Example |
+| --- | --- |
+| PyPI, latest version | `pypi:black` |
+| PyPI, specific version | `pypi:black@24.3.0` |
+| GitHub, default branch | `pypi:psf/black` |
+| GitHub, specific release | `pypi:psf/black@24.3.0` |
+| Git repository | `pypi:git+https://github.com/psf/black.git` |
+| Git branch | `pypi:git+https://github.com/psf/black.git@main` |
+
+For GitHub sources, `latest` installs from the unpinned default branch; it does not select the latest published release. Use an explicit version to select a release. For other Git URLs, `latest` resolves default-branch HEAD to a concrete commit. Remote tags are also available for explicit version requests.
+
+Direct HTTPS archive URLs are unsupported. Other source syntax may work but is unsupported and untested.
+
+## Dependency locking [​](#dependency-locking)
+
+With **uv 0.12.10 or newer**, new `mise.lock` files record the full Python dependency graph, including wheel hashes and Python/platform markers. Locked installs reuse that graph without resolving dependencies again.
+
+Create a lockfile, or upgrade an existing version-only lockfile, then install:
+
+sh
+
+```
+mise lock --upgrade
+mise install --locked
+```
+
+Commit both `mise.lock` and its [dependency sidecar directory](https://mise.jdx.dev/dev-tools/mise-lock.html#native-dependency-sidecars), which contains the native `pyproject.toml` and `uv.lock` files. Existing lockfiles keep version-only behavior until explicitly upgraded.
+
+### Updating dependencies [​](#updating-dependencies)
+
+Ordinary `mise lock` reuses the recorded graph. To refresh a tool's transitive dependencies even when its own version has not changed:
+
+sh
+
+```
+mise lock --bump pypi:black
+```
+
+You can also inspect or edit a sidecar with uv. For a tool locked to Black 24.10.0 in the default sidecar layout:
+
+sh
+
+```
+uv tree --project .mise/locks/pypi-black/24.10.0
+uv lock --project .mise/locks/pypi-black/24.10.0 --upgrade-package click
+mise lock
+```
+
+Run `mise lock` after editing a sidecar to accept its updated digest before using `mise install --locked`.
+
+### Requirements and limitations [​](#requirements-and-limitations)
+
+- **Wheels only for dependency graphs:** every dependency needs a published wheel for the target Python version and platform. Explicit `mise lock` and locked installs do not build source distributions. An ordinary `mise install` falls back to a version-only uv installation when it cannot produce a wheel-only graph.
+- **PyPI packages with uv:** Git sources and standalone pipx installs use version-only locking. pipx cannot replay a uv dependency graph.
+- **No free-form installer arguments in dependency graphs:** `uvx_args` and `pipx_args` use version-only installation during ordinary installs. Explicit dependency locking rejects them because mise cannot safely translate arbitrary installer arguments into a reproducible graph. Use the semantic options instead when dependency locking is required: [`with`](#with) injects additional requirements into the tool environment, [`expose`](#expose) also exposes their executables, and [`dependency_prereleases`](#dependency_prereleases) sets uv's prerelease policy. These are locked together with the tool, so the graph covers the injected packages. Configure [Python](#choosing-python) and the [registry URL](#registry-url) directly as well.
+- **Installed Python required:** lock generation needs an interpreter discoverable by uv, though it need not match the tool's configured Python version. Graph installs use the selected mise Python and do not download a replacement.
+- **Complete lockfiles required:** revision-2 locked uv installs fail if their dependency graph is missing. Run `mise lock` to generate it.
+
+The graph covers the Python range that every locked requirement supports, starting at Python 3.8, and retains all published wheel targets for portability. Requirements injected with [`with`](#with) or [`expose`](#expose) are part of that calculation: one pinned to an exact version raises the range's floor to the release's own `requires-python`, because a single release cannot span the wider range the way uv resolves an unpinned requirement. A pin carrying an environment marker that tests the interpreter, such as `python_version < "3.12"`, is left out, since it is simply absent from the versions it excludes. This can make sidecars large. Frozen installs reuse uv's artifact cache.
+
+Different dependency graphs and configured Python interpreters get separate installations; `mise ls` still shows the package version. For system Python, mise records the interpreter's implementation, major/minor version, ABI, and platform during installation so later commands can find the environment even if that interpreter is no longer on PATH.
+
+### Private indexes and release age [​](#private-indexes-and-release-age)
+
+Simple-only indexes must provide consistent `data-requires-python` metadata on the selected release's wheel links. Registry credentials belong in the installer environment or credential provider. URLs containing credentials or query strings cannot be recorded in the lockfile.
+
+[`minimum_release_age`](https://mise.jdx.dev/configuration/settings.html#minimum_release_age) filters transitive dependencies when resolving a graph, not when replaying it. For version-only installs, mise passes uv's `--exclude-newer` flag (requires uv 0.2.22 or newer) or pip's `--uploaded-prior-to` flag through pipx.
+
+## Choosing Python [​](#choosing-python)
+
+For graph-locked tools, configure the interpreter through mise:
+
+toml
+
+```
+[tools]
+python = "3.14"
+uv = "0.12.10"
+"pypi:black" = "latest"
+```
+
+For legacy version-only installs, the selected installer chooses the interpreter; `uvx_args` and `pipx_args` can pass installer-specific Python options.
+
+## Python upgrades [​](#python-upgrades)
+
+If a CLI stops working after changing Python, reinstall it under the intended Python version. This recreates the tool environment and its dependencies:
+
+sh
+
+```
+mise install --force pypi:black
+mise exec -- black --version
+```
+
+Check which Python version is active before reinstalling. Existing virtualenvs and native extensions do not necessarily remain usable after their interpreter is removed or changed.
+
+## Using pipx [​](#using-pipx)
+
+To use the pipx installer, install Python and pipx, then disable uv for the tool:
+
+sh
+
+```
+mise use python@3.14 pipx
+```
+
+toml
+
+```
+[tools]
+"pypi:ansible" = { version = "latest", uvx = false, expose = [], pipx_args = "--include-deps" }
+```
+
+This uses version-only locking. An existing uv dependency graph cannot be replayed with pipx.
+
+### Compatibility with `pipx:` [​](#compatibility-with-pipx)
+
+The `pipx:` backend name remains supported. Existing configurations do not need to change. However, `pypi:black` and `pipx:black` are distinct tool identities: switching prefixes creates a separate installation and lock entry. mise preserves explicit `pipx:` names in output and lockfiles.
+
+The legacy option names `uvx` and `uvx_args` control uv installation; they do not mean mise runs the `uvx` command.
+
+## Settings [​](#settings)
+
+Set these with `mise settings set [VARIABLE]=[VALUE]` or by setting the environment variable listed.
+
+### `pypi.registry_url`[](#pypi.registry_url)
+
+- Type: `string`(optional)
+- Env: `MISE_PYPI_REGISTRY_URL`
+- Default: `None`
+
+Package registry URL for Python tools (pipx.registry\_url is a compatibility alias).
+
+### `pypi.uvx`[](#pypi.uvx)
+
+- Type: `boolean`(optional)
+- Env: `MISE_PYPI_UVX`
+- Default: `None`
+
+Use uv for Python tools when available (pipx.uvx is a compatibility alias).
+
+## Tool Options [​](#tool-options)
+
+The following [tool-options](https://mise.jdx.dev/dev-tools/#tool-options) are available for the `pypi` backend—these go in `[tools]` in `mise.toml`.
+
+### `registry_url` [​](#registry-url)
+
+Set the registry URL used to resolve versions for this tool. Include a `{}` placeholder for the package name. This overrides the `pypi.registry_url` setting for this tool.
+
+toml
+
+```
+[tools]
+"pypi:my-tool" = { version = "latest", registry_url = "https://packages.example.com/pypi/{}/json" }
+```
+
+Dependency locking also derives the install index from this URL. For version-only installs, configure the install index separately through `uvx_args` or `pipx_args`. For example, with the pipx installer:
+
+toml
+
+```
+[tools]
+"pypi:my-tool" = { version = "latest", uvx = false, registry_url = "https://packages.example.com/pypi/{}/json", pipx_args = "--pip-args='--index-url https://packages.example.com/pypi/simple'" }
+```
+
+### `install_env` [​](#install-env)
+
+Set environment variables for the installer. mise still sets the tool directory, bin directory, and configured Python package index variables after applying `install_env`. For the uv installer, for example:
+
+toml
+
+```
+[tools]
+"pypi:black" = { version = "latest", install_env = { UV_COMPILE_BYTECODE = "1" } }
+```
+
+### `extras` [​](#extras)
+
+Install optional dependencies (Python package extras).
+
+toml
+
+```
+[tools]
+"pypi:harlequin" = { version = "latest", extras = "postgres,s3" }
+# equivalent array form:
+# "pypi:harlequin" = { version = "latest", extras = ["postgres", "s3"] }
+# extras also work with Git sources:
+# "pypi:psf/black" = { version = "latest", extras = ["jupyter"] }
+```
+
+When passing extras inline, use mise's `key=value` tool-option syntax:
+
+bash
+
+```
+mise use 'pypi:psf/black[extras=jupyter]@latest'
+```
+
+For Git repositories whose name differs from the Python distribution name, set `package_name` so mise can build the requirement used to select extras:
+
+toml
+
+```
+[tools]
+"pypi:owner/repository" = { version = "latest", package_name = "distribution", extras = ["feature"] }
+```
+
+### `pipx_args` [​](#pipx-args)
+
+Additional arguments for `pipx install`. These apply only to version-only installs using pipx and are unsupported with dependency graphs.
+
+toml
+
+```
+[tools]
+"pypi:ansible" = { version = "latest", uvx = false, expose = [], pipx_args = "--include-deps" }
+```
+
+### `with` [​](#with)
+
+Install additional Python requirements in the tool environment. This option requires uv and participates in dependency locking.
+
+toml
+
+```
+[tools]
+"pypi:azure-cli" = { version = "latest", with = ["pip"] }
+```
+
+A requirement pinned to an exact version narrows the locked Python range to the versions that release supports, so the tool may end up needing a newer interpreter than it declares on its own. Guard the pin with an interpreter marker, such as `"legacy==1.0.0; python_version < '3.12'"`, to keep the wider range when the requirement is only needed on some versions.
+
+### `expose` [​](#expose)
+
+Install additional Python requirements and expose their executable entry points. This option requires uv 0.8.5 or newer and participates in dependency locking.
+
+toml
+
+```
+[tools]
+"pypi:ansible" = { version = "latest", expose = ["ansible-core"] }
+```
+
+### `dependency_prereleases` [​](#dependency-prereleases)
+
+Set uv's prerelease policy for dependency resolution. Supported values are `disallow`, `allow`, `if-necessary`, and `explicit`. This option requires uv and is applied both when generating dependency graphs and during version-only installs.
+
+toml
+
+```
+[tools]
+"pypi:azure-cli" = { version = "latest", dependency_prereleases = "allow" }
+```
+
+### `uvx` [​](#uvx)
+
+Set to `false` to use pipx instead of uv for this tool. This also disables dependency graph locking and requires pipx to be installed.
+
+toml
+
+```
+[tools]
+"pypi:ansible" = { version = "latest", uvx = false, expose = [] }
+```
+
+The empty `expose` list clears Ansible's uv-backed registry default. Clear any other semantic defaults the same way when overriding a registry tool to use pipx.
+
+### `uvx_args` [​](#uvx-args)
+
+Additional arguments for version-only installs using `uv tool install`. These are unsupported with dependency graphs; `pipx_args` applies only to pipx.
+
+toml
+
+```
+[tools]
+"pypi:ansible-core" = { version = "latest", uvx_args = "--resolution lowest" }
+```
+
+Prefer the semantic [`with`](#with), [`expose`](#expose), and [`dependency_prereleases`](#dependency_prereleases) options when they cover the desired behavior. Unlike arbitrary arguments, those options support dependency graphs.
+
+Implementation: [`src/backend/pipx.rs`](https://github.com/jdx/mise/blob/main/src/backend/pipx.rs).
+
+[Edit this page](https://github.com/jdx/mise/edit/main/docs/dev-tools/backends/pipx.md)
+
+Last updated:
+
+Pager
+
+[Next pageGetting Started](https://mise.jdx.dev/getting-started.html)
+
+MIT License·Copyright © 2026· [![](https://github.com/jdx.png?size=96)jdx.dev](https://jdx.dev)