Switch b4/README.txt to "pipx install" instead of "pip install"?

Switch b4/README.txt to "pipx install" instead of "pip install"?

[Marc Herbert]

Following the current b4/README.txt instructions on any recent Linux
distribution (approx. less than 2 years old) fails instantly with the
well-known "externally managed" error https://peps.python.org/pep-0668/


$ python3 -m pip install b4
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian/Arch/etc.-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    If you wish to install a non-Debian packaged Python application,
==> it may be easiest to use pipx install xyz, which will manage a    <===== pipx =====
    virtual environment for you. Make sure you have pipx installed.
    
    See /usr/share/doc/python3.12/README.venv for more information.


I've been using pipx for months and it Just Works. As stated, it
automates creating, entering and leaving the virtualenv.

I just tested Ubuntu 22.04. It's old enough not to fail like this
(preferring to... actually and silently "break system packages" instead)
but pipx also works just fine on it.

So, should the README simply switch to "pipx install"?

References:
- https://lwn.net/Articles/959236/
- https://repology.org/project/pipx/versions
- https://peps.python.org/pep-0668/

  ------


Also, I'm not an expert but I think installing from source is probably
better done like this:

git clone --recursive b4
cd b4
pipx install -e .

This allows running any version _and_ from the checkout directory
without depending on any "b4.sh" indirection.  The main difference is:
dependencies are isolated/protected in the virtualenv. Some users may
want this, others not.

Anyway that's another debate further down the line.

Re: Switch b4/README.txt to "pipx install" instead of "pip install"?

[Konstantin Ryabitsev]

On Wed, Nov 05, 2025 at 04:20:11PM -0800, Marc Herbert wrote:
> 
> Following the current b4/README.txt instructions on any recent Linux
> distribution (approx. less than 2 years old) fails instantly with the
> well-known "externally managed" error https://peps.python.org/pep-0668/

Yes, this is probably the right course of action.

> So, should the README simply switch to "pipx install"?

If you'd like to submit a patch, I'll be happy to apply it.

> Also, I'm not an expert but I think installing from source is probably
> better done like this:
> 
> git clone --recursive b4
> cd b4
> pipx install -e .
> 
> This allows running any version _and_ from the checkout directory
> without depending on any "b4.sh" indirection.  The main difference is:
> dependencies are isolated/protected in the virtualenv. Some users may
> want this, others not.

This would require having to rerun `pipx install -e .` each time the repo is
pulled though, no?

-K

Re: Switch b4/README.txt to "pipx install" instead of "pip install"?

[Marc Herbert]

Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:

> On Wed, Nov 05, 2025 at 04:20:11PM -0800, Marc Herbert wrote:
>> So, should the README simply switch to "pipx install"?
>
> If you'd like to submit a patch, I'll be happy to apply it.

Sent. If you'd like to fix my English or make some other minor changes,
please just go ahead and do not ask for my permission.

>> Also, I'm not an expert but I think installing from source is probably
>> better done like this:
>> 
>> git clone --recursive b4
>> cd b4
>> pipx install -e .
>> 
>> This allows running any version _and_ from the checkout directory
>> without depending on any "b4.sh" indirection.  The main difference is:
>> dependencies are isolated/protected in the virtualenv. Some users may
>> want this, others not.
>
> This would require having to rerun `pipx install -e .` each time the repo is
> pulled though, no?

Usually not. Possibly yes for upgrading dependencies or some other "big"
change like some packaging re-organization, but not for pure code
changes - that's the whole point. Give it a try?

The only drawback is the same as the advantage: too much virtual env
isolation! It hits you when you try to install and use "on the fly" some
fancy debugger, test plugin, tracing library, Python IDE,... They are
generally "not found". Then you either need to explicity add them to the
manifest, or use some obscure pipx option, or revert to "pip instal
--break-system-packages -e .", or to "b4.sh",...

No silver bullet :-( But for quickly running pure code changes, "pipx
install -e ." is in my experience the best so far.

"uv" is also very useful but much more complex. pipx really makes
simple things easy.

Re: Switch b4/README.txt to "pipx install" instead of "pip install"?

[Konstantin Ryabitsev]

On Fri, Nov 21, 2025 at 01:03:46PM -0800, Marc Herbert wrote:
> > If you'd like to submit a patch, I'll be happy to apply it.
> 
> Sent. If you'd like to fix my English or make some other minor changes,
> please just go ahead and do not ask for my permission.

I followed up already, but if you'd like me to wordsmith the rest myself, I'm
happy to do that -- writing docs is nobody's favourite job. :)

> > This would require having to rerun `pipx install -e .` each time the repo is
> > pulled though, no?
> 
> Usually not. Possibly yes for upgrading dependencies or some other "big"
> change like some packaging re-organization, but not for pure code
> changes - that's the whole point. Give it a try?

I will, thanks for the pointer.

> The only drawback is the same as the advantage: too much virtual env
> isolation! It hits you when you try to install and use "on the fly" some
> fancy debugger, test plugin, tracing library, Python IDE,... They are
> generally "not found". Then you either need to explicity add them to the
> manifest, or use some obscure pipx option, or revert to "pip instal
> --break-system-packages -e .", or to "b4.sh",...

The biggest drawback of anything pip (or pipx) installed is that everything
breaks when I upgrade my distro to the next version and suddenly my Python is
3.14 and not 3.13. :)

-K

Re: Switch b4/README.txt to "pipx install" instead of "pip install"?

[Marc Herbert]

Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:

> On Fri, Nov 21, 2025 at 01:03:46PM -0800, Marc Herbert wrote:
>> > If you'd like to submit a patch, I'll be happy to apply it.
>> 
>> Sent. If you'd like to fix my English or make some other minor changes,
>> please just go ahead and do not ask for my permission.
>
> I followed up already, but if you'd like me to wordsmith the rest myself, I'm
> happy to do that -- writing docs is nobody's favourite job. :)

Please go ahead, otherwise there's a good chance you would spend more
time holding my hand than doing it yourself. Also, don't give me credit
if you make all the changes you requested, that would not reflect
reality.

Making a one-line doc fix is easy, but anything slightly wider requires
a good overview of the whole docs to maintain consistency. You have that
and I don't.

On the other hand, I hope you can eventually work through the backlog
and look at my other, unrelated patch and questions on this list :-)

>> The only drawback is the same as the advantage: too much virtual env
>> isolation! It hits you when you try to install and use "on the fly" some
>> fancy debugger, test plugin, tracing library, Python IDE,... They are
>> generally "not found". Then you either need to explicity add them to the
>> manifest, or use some obscure pipx option, or revert to "pip instal
>> --break-system-packages -e .", or to "b4.sh",...
>
> The biggest drawback of anything pip (or pipx) installed is that everything
> breaks when I upgrade my distro to the next version and suddenly my Python is
> 3.14 and not 3.13. :)

Ah yes, that too! Forgot that other bit of Python fun. I have a special
Trash/ folder for those occasions, too afraid to break something
prematurely...