How to Use uv as a pipx Replacement: The Day My Tooling Broke CI

The Day My CI Failed for No Good Reason

How to use uv as a pipx replacement wasn’t a question I asked out of curiosity.

It was a question I asked out of frustration.

A CI pipeline that had been green for months suddenly failed.
No code changes.
No dependency updates.
No Dockerfile modifications.

Just… red.

Locally, everything worked.
In CI, a simple formatting step failed because the ruff version was different.

That’s when I realized something uncomfortable:

I had no reliable way to explain how my global Python tools were installed anymore.

The Assumption I Never Questioned

I had always treated pipx as infrastructure.

Install once.
Forget forever.

It felt safe because it looked isolated. Each tool lived in its own environment, and I assumed that isolation meant stability.

In reality, it meant hidden state.

• Tools updated independently
• Environments aged silently
• CI machines behaved differently from laptops

It wasn’t broken often—but when it was, the blast radius was large.

That’s the worst kind of failure.

The Moment I Started Questioning pipx

The real problem wasn’t pipx itself.

The problem was opacity.

When something went wrong, I couldn’t answer basic questions confidently:

• Which version of the tool is installed?
• Where did it come from?
• How do I reproduce this setup cleanly?

Those questions matter more in CI than anywhere else.

CI environments are rebuilt constantly. If tooling relies on implicit state, failures become intermittent, non-deterministic, and difficult to trust.

Engineering systems should be explainable.
My Python tooling wasn’t.

Why uv Caught My Attention

I first noticed uv while reading a performance benchmark.

I ignored the speed claims.

What caught my attention instead was how explicit everything was.

No magic environments.
No background state.
No “trust me” abstractions.

Every command did exactly what it said, and nothing more.

That alone made me curious enough to experiment.

The Feature That Made pipx Feel Obsolete

The feature that changed everything was simple:

uv can run tools directly, without installing or persisting environments.

That sounds small. It isn’t.

With pipx, running a tool implies:

• A managed environment
• A lifecycle you don’t fully control
• State that lives longer than you expect

With uv, running a tool is just that—running a tool.

uv run ruff .

No install step.
No cleanup.
No surprises.

That distinction fundamentally changed how I think about tooling.

How I Used pipx Before (And Why It Aged Poorly)

This was my old workflow:

pipx install ruff
pipx install black
pipx install poetry

It worked fine… until it didn’t.

Problems showed up slowly:

• Tool versions drifted
• CI bootstrapping grew complicated
• Reproducibility required documentation, not code

Over time, pipx stopped feeling like infrastructure and started feeling like state I had to remember.

That’s when I realized pipx wasn’t broken — it was just too implicit for how I work now.

How to Use uv as a pipx Replacement (Practically)

Here’s what I actually changed.

Step 1: Install uv Once

pip install uv

After this, pip disappeared from my daily workflow.

Step 2: Run Tools Without Installing Them

For ad-hoc usage:

uv run black .

This alone replaced half my pipx usage.

I stopped thinking about whether a tool was installed and started thinking only about whether I needed to run it.

Step 3: Install Tools Explicitly (pipx-style)

For tools I use constantly:

uv tool install ruff
uv tool install black

That’s the direct, honest answer to
how to use uv as a pipx replacement.

Why This Model Is Easier to Reason About

The biggest win wasn’t speed.

It was explainability.

With this setup:

• Tools are ephemeral (uv run)
• Or explicitly installed (uv tool install)

There’s no third category.

That clarity matters in CI.

If a build fails, I know exactly:

• Which tool ran
• How it was resolved
• Why it behaved the way it did

The Migration Journey (Low-Risk, No Drama)

What Actually Improved (Measured Honestly)

This wasn’t optimization.

It was stability.

When pipx Is Still Fine

To be fair:

If you:

• Rarely touch tooling
• Don’t maintain CI
• Prefer static environments

Then pipx is still acceptable.

What Changed in My Engineering Habits

Once tooling became predictable, I stopped avoiding it.

I upgraded tools more confidently.
I simplified onboarding.
I trusted CI again.

That trust is hard to quantify—but easy to feel.

Final Thoughts

I didn’t switch from pipx to uv because pipx failed.

I switched because uv made fewer assumptions.

Using uv as a pipx replacement aligned my tooling with how I expect production systems to behave: explicit, observable, and boring.

And boring tooling is the best kind.