pipx install fails with "InvalidVersion: Invalid version: ''" — how to fix

[leonardosalasd]

If pipx install fails with InvalidVersion: Invalid version: ''

A couple of people have run into this installing 2.0.0, both on Ubuntu, so here it is in one place.

The short version: your pipx is too old. Update it and the problem goes away.

uv tool install pipx --force     # or: pip install --upgrade pipx
hash -r
pipx install doc-engine-cli

Or skip pipx entirely:

uv tool install doc-engine-cli

What actually happens. mermaidx, which 2.0.0 uses to render diagrams, declares an optional extra named v8. PEP 440 allows a leading v in a version, so v8 parses as version 8. pipx inspects a venv by evaluating every dependency marker with extra set to an empty string; packaging sees what looks like a version comparison, tries to turn "" into a version, and raises.
packaging 25 treats that as fatal, 26 returns false and moves on. pipx 1.17 requires packaging >= 26, so a current pipx is unaffected.

Two things worth knowing if you hit it. The crash happens after pip has finished, while pipx is recording what it installed — so there is often a working copy underneath the traceback, with pipx's bookkeeping still showing the old version. And it is specific to 2.0.0 only because mermaidx arrived with it; 1.1.1 had no dependency declaring an extra that parses as a version.

Nothing here is fixable from this end: the extra name belongs to mermaidx, the marker evaluation belongs to pipx, and the empty-string handling belongs to packaging. I have raised it upstream where it belongs. In the meantime the README says all of this in the install section.

[leonardosalasd]

Fixed at the source. mermaidx 0.9.5 renamed the extra that caused this, so a
fresh install works on any pipx — nothing to work around any more.

doc-engine-cli now requires mermaidx >= 0.9.5. If you are still seeing this,
you have an older mermaidx pinned somewhere; upgrading it is the whole fix.

[johnblommers]

So I found a copy of version 0.9.4 on my system located at

~/.local/share/pipx/venvs/jupyterlab/bin/mermaidx

But Mermaid diagrams are working anyway so no problem.

[leonardosalasd]

That is the one, and there is nothing to do about it. That copy belongs to the venv pipx built for jupyterlab, so it is isolated from doc engine's own — the extra only causes trouble while something is inspecting that venv with an old packaging. Your doc-engine venv picked up 0.9.5 on the reinstall, which is why diagrams render.

If you ever want it gone anyway: pipx runpip jupyterlab install -U mermaidx.

And thank you for staying on top of this repo the way you have. Two releases in a row you brought back something I could not have found from here: the 1.1.1 traceback, and then the install crash, which turned out to be a dependency's metadata and is now fixed upstream in mermaidx itself. That kind of follow-up is rarer than it should be, and it made both releases better.