feat: rename pipx backend to pypi

[halms]

WIP 🚧

After input from @jdx, I'll revisit this, probably rename pipx to pypi rather than uv.

Original note below:

This might be a bit controversial one, but I'll put it here to maybe have a discussion.

The pipx backend has defaulted to using uv tool for a while now and uv has more or less become the default package manager for Python,

So I thought why not rename the backend to uv (while keeping pipx working for now).

[gemini-code-assist]

Summary of Changes

Hello @halms, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request modernizes the Python package management within the system by renaming the pipx backend to uv. This change acknowledges uv's emergence as the de facto standard for Python CLI tools, streamlining terminology and aligning the system with current best practices. The update involves comprehensive documentation revisions and configuration adjustments, while carefully managing the transition with backward compatibility and clear deprecation paths for older pipx references.

Highlights

• Backend Renaming: The pipx backend has been officially renamed to uv to reflect the current default usage of uv tool for Python CLI installations.
• Backward Compatibility & Deprecation: The pipx: prefix will continue to work for now but is deprecated and will emit warnings, encouraging users to transition to uv:.
• Documentation Updates: All relevant documentation, including product guides, tech stack, architecture, backend listings, and glossary, has been updated to reflect the uv backend name and its preferred usage.
• Configuration and Registry Migration: Configuration schemas and numerous tool registry entries have been updated to use the uv: prefix, with legacy pipx and uvx options being deprecated in favor of new uv settings.

Changelog

• .agent-os/instructions/mise-product-guide.md
  • Updated 'Package Managers' list to replace 'pipx' with 'uv tool'.
• .agent-os/standards/mise-tech-stack.md
  • Replaced 'pipx' with 'uv tool' in the Python application installation description.
• docs/architecture.md
  • Updated 'Language Package Managers' list to replace 'pipx' with 'uv'.
• docs/asdf-legacy-plugins.md
  • Replaced 'pipx' with 'uv' in language package manager lists and migration recommendations.
• docs/cli/backends/ls.md
  • Updated the list of backends to show 'uv' instead of 'pipx'.
• docs/contributing.md
  • Replaced 'pipx' with 'uv' in language package manager and existing backend lists.
• docs/dev-tools/backend_architecture.md
  • Replaced 'pipx' with 'uv' in Python package examples, the backend capabilities comparison table, and the dependency graph.
  • Updated black tool options from pipx to uv.
• docs/dev-tools/backends/index.md
  • Updated the description of backends to mention uv as the new name for the pipx backend.
  • Updated the list of available backends to reflect the change from pipx to uv.
• docs/dev-tools/backends/pipx.md
  • Replaced the entire content with a redirect to the new uv backend documentation and noted the deprecation of the pipx backend.
• docs/dev-tools/backends/uv.md
  • Added a new document detailing the uv backend, its usage, dependencies, supported syntax, settings, and tool options.
  • Included deprecation notes for pipx and uvx legacy options within the new uv backend documentation.
• docs/dev-tools/mise-lock.md
  • Updated the list of backends with 'Version only' support to replace 'pipx' with 'uv'.
• docs/getting-started.md
  • Updated section title and examples to use uv instead of pipx for Python tool installations.
• docs/glossary.md
  • Updated the definition for the Python CLI tool installer from pipx to uv.
• docs/mise.usage.kdl
  • Updated the backends ls command output example to list uv instead of pipx.
• docs/registry.data.ts
  • Added a uv entry to the URL mapping for PyPI projects.
• docs/registry.md
  • Updated the preferred backend list to replace pipx with uv for Python tools.
• llms.txt
  • Updated prerequisites to prefer uv over pipx.
  • Updated the language-specific backend list to include uv.
• mise.usage.kdl
  • Updated the mise backends ls command output example to list uv instead of pipx.
• registry/ansible-core.toml
  • Updated backend from pipx:ansible-core to uv:ansible-core.
• registry/ansible.toml
  • Updated backend from pipx:ansible to uv:ansible.
  • Replaced pipx_args and uvx options with uv_tool_args.
• registry/ast-grep.toml
  • Updated backend from pipx:ast-grep-cli to uv:ast-grep-cli.
• registry/aws-sam.toml
  • Updated backend from pipx:aws-sam-cli to uv:aws-sam-cli.
• registry/awscli-local.toml
  • Updated backend from pipx:awscli-local to uv:awscli-local.
• registry/awsebcli.toml
  • Updated backend from pipx:awsebcli to uv:awsebcli.
• registry/azure.toml
  • Updated backend from pipx:azure-cli to uv:azure-cli.
  • Replaced uvx_args option with uv_tool_args.
• registry/cfn-lint.toml
  • Updated backend from pipx:cfn-lint to uv:cfn-lint.
• registry/conan.toml
  • Updated backend from pipx:conan to uv:conan.
• registry/cookiecutter.toml
  • Updated backend from pipx:cookiecutter to uv:cookiecutter.
• registry/copier.toml
  • Updated backend from pipx:copier to uv:copier.
• registry/dvc.toml
  • Updated backend from pipx:dvc to uv:dvc.
• registry/gallery-dl.toml
  • Updated backend from pipx:gallery-dl to uv:gallery-dl.
• registry/ggshield.toml
  • Updated backend from pipx:ggshield to uv:ggshield.
• registry/hatch.toml
  • Updated backend from pipx:hatch to uv:hatch.
• registry/jc.toml
  • Updated backend from pipx:jc to uv:jc.
• registry/meson.toml
  • Updated backend from pipx:meson to uv:meson.
• registry/mitmproxy.toml
  • Updated backend from pipx:mitmproxy to uv:mitmproxy.
• registry/pdm.toml
  • Updated backend from pipx:pdm to uv:pdm.
• registry/pipenv.toml
  • Updated backend from pipx:pipenv to uv:pipenv.
• registry/poetry.toml
  • Updated backend from pipx:poetry to uv:poetry.
• registry/pre-commit.toml
  • Updated backend from pipx:pre-commit to uv:pre-commit.
• registry/semgrep.toml
  • Updated backend from pipx:semgrep to uv:semgrep.
• registry/sshuttle.toml
  • Updated backend from pipx:sshuttle to uv:sshuttle.
• registry/uv.toml
  • Updated backend from pipx:uv to uv:uv.
• registry/xxh.toml
  • Updated backend from pipx:xxh-xxh to uv:xxh-xxh.
• registry/yamllint.toml
  • Updated backend from pipx:yamllint to uv:yamllint.
• schema/mise-registry-tool.json
  • Updated the regex pattern for backend specifications to include uv.
• schema/mise.json
  • Updated the description for disable_backends to mention uv instead of pipx.
  • Added a new uv settings object with registry_url and pipx properties.
  • Deprecated pipx and pipx_uvx settings, marking them for future removal.
• settings.toml
  • Updated the description for disable_backends to mention uv instead of pipx.
  • Updated the description for release_timestamp to include uv.
  • Added new uv.registry_url and uv.pipx settings.
  • Deprecated pipx.registry_url, pipx.uvx, and pipx_uvx settings with future removal dates.
• src/backend/backend_type.rs
  • Renamed BackendType::Pipx to BackendType::UvTool.
  • Added #[strum(serialize = "uv", serialize = "pipx")] to UvTool to allow both prefixes.
  • Implemented display logic to output 'uv' for UvTool.
  • Introduced a deprecation warning for the pipx prefix when parsed.
• src/backend/mod.rs
  • Renamed the pipx module to uv_tool.
  • Updated references to the pipx backend to uv_tool.
• src/backend/pipx.rs
  • Renamed to src/backend/uv_tool.rs.
• src/backend/uv_tool.rs
  • Refactored the PIPXBackend struct to UvToolBackend.
  • Updated get_dependencies and get_optional_dependencies to prioritize uv and handle pipx as a fallback based on settings.
  • Modified _list_remote_versions to use UvToolRequest instead of PipxRequest.
  • Updated install_version_ logic to prefer uv tool for installation, with pipx as a configurable fallback.
  • Introduced uv_tool_args and warn_deprecated_uv_legacy_options functions to manage new and deprecated options.
  • Updated install_time_option_keys to include new uv_tool_args and uv_tool options, alongside legacy aliases.
  • Adjusted get_registry_url to use uv.registry_url from settings.
  • Updated reinstall_all to refer to uv tools and use uv_tool_cmd or pipx_cmd accordingly.
  • Renamed uvx_cmd to uv_tool_cmd.
  • Renamed PipxRequest enum to UvToolRequest and updated its methods.
• src/cli/args/backend_arg.rs
  • Added a deprecation warning when the pipx: prefix is used in BackendArg::from.
• src/cli/backends/ls.rs
  • Updated the AFTER_LONG_HELP example to list uv instead of pipx.
• src/cli/edit.rs
  • Updated the backend provider description for Python CLI tools to refer to uv.
• src/cli/install.rs
  • Updated a comment to reflect uv:* wildcard expansion instead of pipx:*.
• src/cli/search.rs
  • Updated the URL generation for PyPI projects to include uv as a valid backend type.
• src/cli/upgrade.rs
  • Updated the reinstall_all function to use UvToolBackend and refer to uv tools.
• src/config/settings.rs
  • Modified disable_backends logic to automatically map 'pipx' to 'uv' if 'pipx' is disabled.
  • Updated logic for pipx_uvx and pipx.uvx settings to map to the new uv.pipx setting.
  • Ensured uv.registry_url defaults to pipx.registry_url if pipx.registry_url was customized, for migration purposes.

Activity

• The pull request was opened by halms to initiate a discussion around renaming the pipx backend to uv.
• The author justified the change by noting that uv tool has become the de facto default for Python package management and the pipx backend already defaults to using uv tool.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request renames the pipx backend to uv, reflecting the shift in the Python ecosystem. This is a significant refactoring that touches numerous documentation files, configuration schemas, and the core backend logic. The changes are mostly correct, but I've identified a couple of logical issues in the new uv_tool backend implementation concerning the logic that decides whether to use uv tool or the pipx fallback. I have provided suggestions to correct this logic and ensure consistency with the documentation.

[Copilot]

Pull request overview

Renames the Python CLI-tools backend from pipx to uv (backed by uv tool), while keeping pipx: as a deprecated alias and migrating related settings/registry entries.

Changes:

• Introduce uv as the primary backend identifier (aliasing pipx → uv) and update CLI/help/docs accordingly.
• Add uv.* settings + JSON schema support, and migrate legacy pipx.* settings/flags to the new names.
• Update built-in registry tool definitions to use uv: instead of pipx:.

Reviewed changes

Copilot reviewed 58 out of 58 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/config/settings.rs	Migrates disabled backends and legacy pipx settings to uv settings.
src/cli/upgrade.rs	Reinstalls Python CLI tools via the renamed backend after Python upgrades.
src/cli/search.rs	Treats uv (and legacy pipx) as PyPI-backed for URL generation.
src/cli/install.rs	Updates wildcard example to uv:*.
src/cli/edit.rs	Updates backend display label from pipx to uv.
src/cli/backends/ls.rs	Updates backend list output to show uv instead of pipx.
src/cli/args/backend_arg.rs	Emits deprecation warning for pipx: prefix usage.
src/backend/uv_tool.rs	Renames/repurposes backend implementation to UvToolBackend and adds legacy-option handling.
src/backend/mod.rs	Switches module export and backend factory wiring from pipx to uv_tool.
src/backend/backend_type.rs	Introduces UvTool backend type serialized as uv and pipx (deprecated).
settings.toml	Adds uv.* settings, deprecates pipx.* settings, updates docs/metadata.
schema/mise.json	Adds uv settings to JSON schema and marks pipx settings deprecated.
schema/mise-registry-tool.json	Allows uv: backend prefix in registry tool schemas (keeps pipx: too).
registry/yamllint.toml	Switch registry backend entry to uv:.
registry/xxh.toml	Switch registry backend entry to uv:.
registry/uv.toml	Switch registry backend entry to uv: for installing uv itself.
registry/sshuttle.toml	Switch registry backend entry to uv:.
registry/semgrep.toml	Switch registry backend entry to uv:.
registry/pre-commit.toml	Switch registry backend entry to uv:.
registry/poetry.toml	Switch registry backend entry to uv:.
registry/pipenv.toml	Switch registry backend entry to uv:.
registry/pdm.toml	Switch registry backend entry to uv:.
registry/mitmproxy.toml	Switch registry backend entry to uv:.
registry/meson.toml	Switch registry backend entry to uv:.
registry/jc.toml	Switch registry backend entry to uv:.
registry/hatch.toml	Switch registry backend entry to uv:.
registry/ggshield.toml	Switch registry backend entry to uv:.
registry/gallery-dl.toml	Switch registry backend entry to uv:.
registry/dvc.toml	Switch registry backend entry to uv:.
registry/copier.toml	Switch registry backend entry to uv:.
registry/cookiecutter.toml	Switch registry backend entry to uv:.
registry/conan.toml	Switch registry backend entry to uv:.
registry/cfn-lint.toml	Switch registry backend entry to uv:.
registry/azure.toml	Switch backend to uv: and rename legacy uvx_args to uv_tool_args.
registry/awsebcli.toml	Switch registry backend entry to uv:.
registry/awscli-local.toml	Switch registry backend entry to uv:.
registry/aws-sam.toml	Switch registry backend entry to uv:.
registry/ast-grep.toml	Switch registry backend entry to uv:.
registry/ansible.toml	Switch backend to uv: and update options to uv_tool_args.
registry/ansible-core.toml	Switch registry backend entry to uv:.
mise.usage.kdl	Updates CLI usage text to show uv backend in lists.
llms.txt	Updates contributor-facing docs references from pipx to uv.
docs/registry.md	Updates recommended backend list entry from pipx to uv.
docs/registry.data.ts	Adds uv → PyPI URL mapping.
docs/mise.usage.kdl	Updates docs usage snippet to list uv.
docs/glossary.md	Updates glossary entry from pipx to uv (formerly pipx).
docs/getting-started.md	Updates getting started examples and diagrams from pipx to uv.
docs/dev-tools/mise-lock.md	Updates backend capability list from pipx to uv.
docs/dev-tools/backends/uv.md	Adds new uv backend documentation page.
docs/dev-tools/backends/pipx.md	Replaces pipx doc with a pointer to the uv docs + deprecation note.
docs/dev-tools/backends/index.md	Updates backend index to reference uv instead of pipx.
docs/dev-tools/backend_architecture.md	Updates architecture docs from pipx to uv.
docs/contributing.md	Updates contributing guidance referencing language package managers.
docs/cli/backends/ls.md	Updates backend list doc output to show uv.
docs/asdf-legacy-plugins.md	Updates doc references from pipx to uv.
docs/architecture.md	Updates architecture overview from pipx to uv.
.agent-os/standards/mise-tech-stack.md	Updates tech stack reference from pipx to uv tool.
.agent-os/instructions/mise-product-guide.md	Updates product guide references from pipx to uv tool.

Comments suppressed due to low confidence (3)

src/backend/uv_tool.rs:213

• uv.pipx is defined as “use pipx instead of uv tool”, but this condition treats uv.pipx == Some(true) as still allowing uv tool (!= Some(false)). This inverts the meaning of the setting; the check should disable uv tool when uv.pipx is true, not when it is false. Also, the legacy uvx option previously used uvx=false to disable uv, but this code disables uv when uvx=true instead.
  src/backend/uv_tool.rs:223
• The warning suggests “set uv_tool = false for this tool”, but install_version_ never reads a uv_tool option to influence backend selection (it only checks pipx and legacy uvx). This makes the message inaccurate and the documented override ineffective; either implement uv_tool handling (and map uvx -> uv_tool) or adjust the message to point users to the actually supported option.
  src/backend/uv_tool.rs:294
• resolve_lockfile_options persists uv_tool (and maps legacy uvx to it), but install_version_ does not consult uv_tool at all when deciding between uv tool and pipx. This means lockfiles (and user config) may not reproduce the intended installer choice. Consider using uv_tool (and legacy uvx) consistently in the selection logic.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[halms]

/gemini review

[gemini-code-assist]

Code Review

This PR is a large refactoring to rename the pipx backend to uv, reflecting that uv is now the default tool used. The changes are extensive, touching documentation, configuration schemas, and core backend logic. The refactoring is well-executed, with consideration for backward compatibility by keeping the pipx: prefix working with a deprecation warning and handling legacy settings. I've found a couple of minor inconsistencies in the new uv_tool.rs backend implementation related to option naming and deprecation messages that should be addressed for clarity.

[Copilot]

Pull request overview

Copilot reviewed 60 out of 60 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (5)

src/backend/uv_tool.rs:223

• The error message mentions setting uv_tool = false, but according to the documentation and the actual code logic (line 211), the correct option name is pipx = true (not uv_tool). This should be updated to say "(or set pipx = true for this tool)" to match the actual option name.
  src/backend/uv_tool.rs:484
• The deprecation warning suggests using uv_tool instead of uvx, but according to the documentation and the actual code logic (line 211), the correct option name is pipx. This should be updated to say "Option uvx is deprecated; use pipx instead." to match the actual option name.
  src/backend/uv_tool.rs:313
• The option uv_tool is listed in install_time_option_keys but is not actually used anywhere in the code. According to the documentation and implementation, the correct option name is pipx (not uv_tool). This entry should either be changed to "pipx".into() or removed if pipx is already included elsewhere. Based on the implementation, it appears this should be "pipx".into().
  src/backend/uv_tool.rs:62
• The comment refers to "Pipx" but this is now the UV tool backend. This should be updated to say "UV tool installs" or "This backend installs" to reflect the rename from pipx to uv.
  src/backend/uv_tool.rs:300
• The function warn_deprecated_uv_legacy_options is called both in the conditional logic here (lines 293, 299) and at the start of install_version_ (line 206). If resolve_lockfile_options is called during an installation flow, users might see duplicate deprecation warnings. Consider only calling the warning function once at the entry point (install_version_) to avoid duplicate warnings, or add a check to ensure the warning is only shown once per tool installation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[lucasew]

IMHO if there is no breaking change in that it's not a problem.

And UV is mature enough today to be default.

[jdx]

I think that pipx was the wrong name (pip would've been better), but I'm not sure that uv is the right one. I feel like it should reference the name of the registry, not the tool to install—so maybe pypi. It's worth considering that we may want to adopt pyx later and would want a good way to achieve that.

[halms]

Good point!

So we'd go for pypi which by default uses uv tool but also can do pipx.

About breaking changes:
There is only a minimal change to e2e tests, so I think we should be rather safe here.

[lucasew]

Standardise on the name of the source/registry instead of the name of the tool really sounds like a better approach

[jdx]

yeah, I kind of think that "pypi:" vs "pyx:" would make a natural onramp and work similarly to gitlab:/github: which I think has been working well. It's a lot better than uv:foo[registry=pyx] would be

[jdx]

that said, please challenge me on this if you disagree—I am very much not a python dev

[jdx]

seeing if charlie has any thoughts on the matter: https://x.com/jdxcode/status/2024533166547951618?s=20

[halms]

please challenge me on this if you disagree

No disagreement. pypi makes most sense to me.
For many others (cargo, npm, ...) tool and registry is named the same, so that discussion was never faced.

There are some other backends, where this could open a naming discussion: dotnet, possibly gem,

[jdx]

actually cargo is a bad example, if we followed the same pattern it would be "crate:", but I feel like that'd be pretty unidiomatic and in rust it's hard to imagine a tool capable of competing with cargo

[lucasew]

well, the name of the site is crates.io, following the same approach gem would be rubygems

[halms]

I just figured this:

The docs for the backend state

The pipx backend supports the following sources:

• PyPI
• Git
• GitHub
• Http

First, the Http in there is wrong.
While uv and pipx support something like uv tool install https://github.com/psf/black/archive/18.9b0.zip,
the code that handles this in mise does not.

But that aside, the backend not only supports pypi, but also different sources, which might make naming it pypi inconsistent.

So maybe stick with uv as name? Or something like python?
Maybe could allow something like: (but I do get this could be a larger change)

• uv:black -> pypi black (default. shorthand)
• uv:pypi:black -> more explicit
• uv:psf/black -> GitHub psf/black (default, shorthand)
• uv:gh:psf/black or uv:github:psf/black -> more explicit
• and in the future: uv:pyx:...