<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/pip-vs-pipx-vs-uv/">
  <id>https://docs.spec-kitty.ai/architecture/pip-vs-pipx-vs-uv/</id>
  <title>Pip vs pipx vs uv — which installer should you use?</title>
  <updated>2026-09-30T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/pip-vs-pipx-vs-uv/"/>
  <summary>Choosing a Python installer for the Spec Kitty CLI: pipx by default, uv tool for uv teams, pip in a venv for contributors, and why per-tool isolation and PEP 668 matter.</summary>
  <content type="html">&lt;span id=&quot;pip-vs-pipx-vs-uv--which-installer-should-you-use&quot;&gt;&lt;/span&gt;
&lt;p&gt;Spec Kitty supports installing the CLI with three Python tools: &lt;code dir=&quot;auto&quot;&gt;pip&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pipx&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;uv tool&lt;/code&gt;. They are not interchangeable. This page explains the difference and recommends the right choice for your situation.&lt;/p&gt;
&lt;h2 id=&quot;the-short-answer&quot;&gt;The short answer&lt;/h2&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;You are…&lt;/th&gt;&lt;th&gt;Use&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;An end user who wants &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; on your PATH&lt;/td&gt;&lt;td&gt;&lt;strong&gt;pipx&lt;/strong&gt; (or &lt;strong&gt;uv tool&lt;/strong&gt;)&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;A team standardizing on &lt;code dir=&quot;auto&quot;&gt;uv&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;strong&gt;uv tool&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;A contributor working inside a clone of &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;strong&gt;pip in a venv&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Anyone else&lt;/td&gt;&lt;td&gt;&lt;strong&gt;pipx&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2 id=&quot;overview-of-each-tool&quot;&gt;Overview of each tool&lt;/h2&gt;
&lt;h3 id=&quot;pip&quot;&gt;pip&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;pip&lt;/code&gt; is the standard Python package installer. It installs into whatever Python environment you tell it to — system Python, a venv, conda, etc. It does &lt;strong&gt;not&lt;/strong&gt; create isolation for you; it installs alongside everything else in that environment.&lt;/p&gt;
&lt;p&gt;Use cases:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Installing dependencies into an explicit virtual environment you manage.&lt;/li&gt;
&lt;li&gt;CI/CD images with a dedicated Python.&lt;/li&gt;
&lt;li&gt;Contributing to a Python project that you have cloned.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;pipx&quot;&gt;pipx&lt;/h3&gt;
&lt;p&gt;&lt;a href=&quot;https://pipx.pypa.io/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;pipx&lt;/code&gt;&lt;/a&gt; is built on top of &lt;code dir=&quot;auto&quot;&gt;pip&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;venv&lt;/code&gt;. It installs each Python &lt;strong&gt;application&lt;/strong&gt; (anything that exposes console scripts) into its own dedicated venv, then symlinks the script onto your PATH. You get isolation per-tool without managing venvs yourself.&lt;/p&gt;
&lt;p&gt;Use cases:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Installing CLI applications globally, with isolation.&lt;/li&gt;
&lt;li&gt;Running occasional one-shot tools with &lt;code dir=&quot;auto&quot;&gt;pipx run&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Any modern Linux distro with PEP 668 &lt;code dir=&quot;auto&quot;&gt;externally-managed-environment&lt;/code&gt; rules.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;uv-tool&quot;&gt;uv tool&lt;/h3&gt;
&lt;p&gt;&lt;a href=&quot;https://docs.astral.sh/uv/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;uv&lt;/code&gt;&lt;/a&gt; is a fast, Rust-based Python toolchain. Its &lt;code dir=&quot;auto&quot;&gt;uv tool&lt;/code&gt; subcommand is conceptually similar to &lt;code dir=&quot;auto&quot;&gt;pipx&lt;/code&gt; — install applications into isolated venvs, expose their scripts — but it uses uv’s parallel resolver and aggressive caching, so installs and upgrades are much faster.&lt;/p&gt;
&lt;p&gt;Use cases:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;You already use &lt;code dir=&quot;auto&quot;&gt;uv&lt;/code&gt; for project dependency management and want one tool for everything.&lt;/li&gt;
&lt;li&gt;Speed matters (CI cold-installs, frequent reinstalls).&lt;/li&gt;
&lt;li&gt;You want lockfile-like reproducibility for tool installs.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;comparison&quot;&gt;Comparison&lt;/h2&gt;













































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Tool&lt;/th&gt;&lt;th&gt;Isolation&lt;/th&gt;&lt;th&gt;Speed&lt;/th&gt;&lt;th&gt;Reproducibility&lt;/th&gt;&lt;th&gt;Cross-platform&lt;/th&gt;&lt;th&gt;Recommended for&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;pip&lt;/strong&gt; (system)&lt;/td&gt;&lt;td&gt;None (shared env)&lt;/td&gt;&lt;td&gt;Medium&lt;/td&gt;&lt;td&gt;Manual&lt;/td&gt;&lt;td&gt;macOS / Linux / Windows&lt;/td&gt;&lt;td&gt;Avoid for global tools&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;pip&lt;/strong&gt; (venv)&lt;/td&gt;&lt;td&gt;Per-venv&lt;/td&gt;&lt;td&gt;Medium&lt;/td&gt;&lt;td&gt;Manual via &lt;code dir=&quot;auto&quot;&gt;requirements.txt&lt;/code&gt;&lt;/td&gt;&lt;td&gt;macOS / Linux / Windows&lt;/td&gt;&lt;td&gt;Contributors, CI&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;pipx&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Per-tool venv (automatic)&lt;/td&gt;&lt;td&gt;Medium&lt;/td&gt;&lt;td&gt;Pin via &lt;code dir=&quot;auto&quot;&gt;==&lt;/code&gt;&lt;/td&gt;&lt;td&gt;macOS / Linux / Windows&lt;/td&gt;&lt;td&gt;Default for global tool install&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;uv tool&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Per-tool venv (automatic)&lt;/td&gt;&lt;td&gt;Fast&lt;/td&gt;&lt;td&gt;Pin via &lt;code dir=&quot;auto&quot;&gt;==&lt;/code&gt;; uv caches resolutions&lt;/td&gt;&lt;td&gt;macOS / Linux / Windows&lt;/td&gt;&lt;td&gt;Teams standardizing on uv&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;why-isolation-matters&quot;&gt;Why isolation matters&lt;/h3&gt;
&lt;p&gt;When you &lt;code dir=&quot;auto&quot;&gt;pip install spec-kitty-cli&lt;/code&gt; into a system Python, the install shares site-packages with every other Python program on the machine. A future &lt;code dir=&quot;auto&quot;&gt;pip install some-other-tool&lt;/code&gt; can silently upgrade a dependency that breaks spec-kitty. With &lt;code dir=&quot;auto&quot;&gt;pipx&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;uv tool&lt;/code&gt;, each tool has its own venv, so dependency conflicts cannot happen.&lt;/p&gt;
&lt;p&gt;This is also why modern distributions (Ubuntu 24.04, Debian 12, Fedora) refuse &lt;code dir=&quot;auto&quot;&gt;pip install&lt;/code&gt; against system Python — PEP 668 declares those interpreters externally managed, and direct installs corrupt the OS.&lt;/p&gt;
&lt;h3 id=&quot;why-contributors-use-pip-in-a-venv&quot;&gt;Why contributors use pip in a venv&lt;/h3&gt;
&lt;p&gt;If you are working &lt;strong&gt;on&lt;/strong&gt; Spec Kitty (not just with it), you clone the repository and install in editable mode:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;clone&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;https://github.com/spec-kitty/spec-kitty&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-m&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;venv&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.venv&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;source&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.venv/bin/activate&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;pip&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;install&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-e&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Editable mode (&lt;code dir=&quot;auto&quot;&gt;-e .&lt;/code&gt;) means edits to &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/&lt;/code&gt; are picked up immediately. Neither &lt;code dir=&quot;auto&quot;&gt;pipx&lt;/code&gt; nor &lt;code dir=&quot;auto&quot;&gt;uv tool&lt;/code&gt; are designed for that workflow — they are about installing finished applications.&lt;/p&gt;
&lt;h2 id=&quot;common-quirks&quot;&gt;Common quirks&lt;/h2&gt;
&lt;h3 id=&quot;pip-1&quot;&gt;pip&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Direct installs against modern system Python fail with &lt;code dir=&quot;auto&quot;&gt;externally-managed-environment&lt;/code&gt;. This is correct behavior — switch to pipx, uv tool, or a venv.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pip install --user&lt;/code&gt; puts scripts in &lt;code dir=&quot;auto&quot;&gt;~/.local/bin&lt;/code&gt;, which may not be on PATH.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pip install --upgrade&lt;/code&gt; upgrades to the latest matching version, but does not remove obsolete dependencies. Use &lt;code dir=&quot;auto&quot;&gt;pip-autoremove&lt;/code&gt; or a fresh venv if cleanliness matters.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;pipx-1&quot;&gt;pipx&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The shim directory (&lt;code dir=&quot;auto&quot;&gt;~/.local/bin&lt;/code&gt;) must be on PATH. &lt;code dir=&quot;auto&quot;&gt;pipx ensurepath&lt;/code&gt; handles this once.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pipx upgrade --pip-args=--pre spec-kitty-cli&lt;/code&gt; only sees PyPI; for git installs, use &lt;code dir=&quot;auto&quot;&gt;pipx install --force&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pipx reinstall&lt;/code&gt; is occasionally needed after major Python upgrades (3.11 → 3.12) so the tool venv uses the new interpreter.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;uv-tool-1&quot;&gt;uv tool&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;The shim directory varies by installer (Astral installer uses &lt;code dir=&quot;auto&quot;&gt;~/.local/bin&lt;/code&gt; in current releases; older installers used &lt;code dir=&quot;auto&quot;&gt;~/.cargo/bin&lt;/code&gt;). Verify with &lt;code dir=&quot;auto&quot;&gt;uv tool dir --bin&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;uv tool&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;pipx&lt;/code&gt; cannot manage the same installation — pick one tool per machine for &lt;code dir=&quot;auto&quot;&gt;spec-kitty-cli&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;uv tool upgrade &amp;#x3C;name&gt;&lt;/code&gt; requires the tool to have been originally installed via &lt;code dir=&quot;auto&quot;&gt;uv tool install&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;recommendation&quot;&gt;Recommendation&lt;/h2&gt;
&lt;p&gt;For most users, &lt;strong&gt;pipx&lt;/strong&gt; is the right default. It is:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Officially blessed by the Python packaging ecosystem.&lt;/li&gt;
&lt;li&gt;Available on every major distribution.&lt;/li&gt;
&lt;li&gt;Self-contained — &lt;code dir=&quot;auto&quot;&gt;pipx install --pip-args=--pre spec-kitty-cli&lt;/code&gt; is one command.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;If your team has already standardized on uv, prefer &lt;code dir=&quot;auto&quot;&gt;uv tool install --prerelease=allow spec-kitty-cli&lt;/code&gt; so all your Python tooling lives in the same place.&lt;/p&gt;
&lt;p&gt;Only fall back to &lt;code dir=&quot;auto&quot;&gt;pip in a venv&lt;/code&gt; when you are managing the venv intentionally (contributors, CI/CD, special interpreters).&lt;/p&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/installation/install-macos/&quot;&gt;Install on macOS&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/installation/install-linux/&quot;&gt;Install on Linux&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/installation/install-windows/&quot;&gt;Install on Windows&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/installation/upgrade-cli/&quot;&gt;Upgrade the CLI&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://pipx.pypa.io/&quot;&gt;pipx docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://docs.astral.sh/uv/&quot;&gt;uv docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;https://peps.python.org/pep-0668/&quot;&gt;PEP 668: externally managed environments&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
