[v2,1/2] ref-manual/system-requirements.rst: make python3-websockets a default host requirement

When configuring the project through bitbake-setup we can choose the
"poky-with-sstate" configuration, which requires the python3-websockets
package.

Add this package as a host requirement (under different names depending
on the distro).

Alma, CentOS, and Rocky have a requirement on the buildtools tarball,
which already contains this package, so we don't need to add it for
them.

On Ubuntu 22.04 and Debian 11, the version of python3-websockets
provided by the distribution is too old compared to what we need [1].
Add a separate set of instructions for these.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/ref-manual/system-requirements.rst   | 28 ++++++++++++++++++++++
 .../host_packages_scripts/fedora_essential.sh      |  2 +-
 .../opensuse_essential_16.0.sh                     |  2 +-
 3 files changed, 30 insertions(+), 2 deletions(-)

Hi Antonin,

On 4/20/26 11:52 AM, Antonin Godard via lists.yoctoproject.org wrote:
> When configuring the project through bitbake-setup we can choose the
> "poky-with-sstate" configuration, which requires the python3-websockets
> package.
> 
> Add this package as a host requirement (under different names depending
> on the distro).
> 
> Alma, CentOS, and Rocky have a requirement on the buildtools tarball,
> which already contains this package, so we don't need to add it for
> them.
> 
> On Ubuntu 22.04 and Debian 11, the version of python3-websockets
> provided by the distribution is too old compared to what we need [1].
> Add a separate set of instructions for these.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/ref-manual/system-requirements.rst   | 28 ++++++++++++++++++++++
>   .../host_packages_scripts/fedora_essential.sh      |  2 +-
>   .../opensuse_essential_16.0.sh                     |  2 +-
>   3 files changed, 30 insertions(+), 2 deletions(-)
> 
> diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
> index 298832dd9..baa965573 100644
> --- a/documentation/ref-manual/system-requirements.rst
> +++ b/documentation/ref-manual/system-requirements.rst
> @@ -166,6 +166,34 @@ Ubuntu and Debian
>   
>   .. include:: ubuntu-debian-host-packages-nodocs.rst
>   
> +Additionally, on distributions other than Debian 11 and Ubuntu 22.04 (otherwise
> +see note below), install the following package:
> +
> +.. code-block:: console
> +
> +   $ sudo apt install python3-websockets
> +

Maybe use apt-get here? I know we have one or the other across the 
code-base. For some reason, I can't bring myself to use apt, it always 
results in weird behaviors I don't have using apt-get on servers (I 
don't run Debian-based on my own machines).

> +.. note::
> +
> +   On Debian 11 and Ubuntu 22.04, the requirement on the version of

A bit awkward wording to me, would

the minimum version for ``python3-websockets`` is not satisfied...

work better?

> +   ``python3-websockets`` is not satisfied by the host distribution. This
> +   package is used for fetching pre-built :ref:`shared state
> +   <overview-manual/concepts:shared state>` artifacts from upstream Yocto Project
> +   servers (see :ref:`ref-fragments-core-yocto-sstate-mirror-cdn` for more
> +   information).
> +
> +   In order to use this feature, you can get the correct version of
> +   ``python3-websockets`` by either:
> +
> +   -  Using a :term:`buildtools` tarball by following the
> +      :ref:`system-requirements-buildtools` section below.
> +
> +   -  Installing ``python3-websockets`` using `Pip <https://pip.pypa.io/en/stable/>`__:
> +
> +      .. code-block:: console
> +
> +         $ pip install websockets
> +

websockets 9.1 supports Python 3.9 which is available in Debian 11 and 
Ubuntu 22.04 so it'll get at least that version (it's not because a 
newer version of a package is available on PyPI that your system can 
install it; and the opposite is true, you may have a too new Python 
version for the last package version available (e.g. tensorflow-lite 
isn't compatible with Python 3.14)). Can you check what happens if the 
user already has python3-websockets installed on the system and runs 
this command? My hunch is it'll not get updated to >=9.1 without 
-U/--upgrade. Also, running -U will likely break their system if any of 
the hsot packages depend on that older version of websockets... Maybe we 
should only be using Python packages from a virtualenv?

>   Here are the packages needed to build Project documentation manuals:
>   
>   .. literalinclude:: ../tools/host_packages_scripts/ubuntu_docs.sh
> diff --git a/documentation/tools/host_packages_scripts/fedora_essential.sh b/documentation/tools/host_packages_scripts/fedora_essential.sh
> index 99e5d2c0b..55b8b704b 100644
> --- a/documentation/tools/host_packages_scripts/fedora_essential.sh
> +++ b/documentation/tools/host_packages_scripts/fedora_essential.sh
> @@ -1 +1 @@
> -sudo dnf install bzip2 ccache chrpath cpio cpp diffstat diffutils file findutils gawk gcc gcc-c++ git glibc-devel glibc-langpack-en gzip hostname libacl make patch perl perl-Data-Dumper perl-File-Compare perl-File-Copy perl-FindBin perl-Text-ParseWords perl-Thread-Queue perl-bignum perl-locale python python3 python3-GitPython python3-jinja2 python3-pexpect python3-pip rpcgen socat tar texinfo unzip wget which xz zstd $([ $(rpm -E %fedora) -ge 42 ] && echo "util-linux-script")
> +sudo dnf install bzip2 ccache chrpath cpio cpp diffstat diffutils file findutils gawk gcc gcc-c++ git glibc-devel glibc-langpack-en gzip hostname libacl make patch perl perl-Data-Dumper perl-File-Compare perl-File-Copy perl-FindBin perl-Text-ParseWords perl-Thread-Queue perl-bignum perl-locale python python3 python3-GitPython python3-jinja2 python3-pexpect python3-pip python3-websockets rpcgen socat tar texinfo unzip wget which xz zstd $([ $(rpm -E %fedora) -ge 42 ] && echo "util-linux-script")
> diff --git a/documentation/tools/host_packages_scripts/opensuse_essential_16.0.sh b/documentation/tools/host_packages_scripts/opensuse_essential_16.0.sh
> index e557ae4fb..96bdd9317 100644
> --- a/documentation/tools/host_packages_scripts/opensuse_essential_16.0.sh
> +++ b/documentation/tools/host_packages_scripts/opensuse_essential_16.0.sh
> @@ -1 +1 @@
> -sudo zypper install bzip2 chrpath diffstat gcc gcc-c++ git gzip hostname libacl1 make makeinfo patch python3 python3-GitPython python3-Jinja2 python3-curses python3-pexpect python3-pip python3-xml rpcgen socat tar wget which xz zstd
> +sudo zypper install bzip2 chrpath diffstat gcc gcc-c++ git gzip hostname libacl1 make makeinfo patch python3 python3-GitPython python3-Jinja2 python3-curses python3-pexpect python3-pip python313-websockets python3-xml rpcgen socat tar wget which xz zstd

Can you rather use python3-websockets here? 
https://opensuse.pkgs.org/16.0/opensuse-oss/python313-websockets-14.2-160000.2.2.aarch64.rpm.html 
says it provides and replaces python3-websockets. That should make the 
upgrade to the next Leap version easier since I'm assuming it may switch 
to Python 3.14 by then?

Cheers,
Quentin

Hi,

On Mon Apr 20, 2026 at 12:43 PM CEST, Quentin Schulz wrote:
> Hi Antonin,
>
> On 4/20/26 11:52 AM, Antonin Godard via lists.yoctoproject.org wrote:
>> When configuring the project through bitbake-setup we can choose the
>> "poky-with-sstate" configuration, which requires the python3-websockets
>> package.
>> 
>> Add this package as a host requirement (under different names depending
>> on the distro).
>> 
>> Alma, CentOS, and Rocky have a requirement on the buildtools tarball,
>> which already contains this package, so we don't need to add it for
>> them.
>> 
>> On Ubuntu 22.04 and Debian 11, the version of python3-websockets
>> provided by the distribution is too old compared to what we need [1].
>> Add a separate set of instructions for these.
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/ref-manual/system-requirements.rst   | 28 ++++++++++++++++++++++
>>   .../host_packages_scripts/fedora_essential.sh      |  2 +-
>>   .../opensuse_essential_16.0.sh                     |  2 +-
>>   3 files changed, 30 insertions(+), 2 deletions(-)
>> 
>> diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst
>> index 298832dd9..baa965573 100644
>> --- a/documentation/ref-manual/system-requirements.rst
>> +++ b/documentation/ref-manual/system-requirements.rst
>> @@ -166,6 +166,34 @@ Ubuntu and Debian
>>   
>>   .. include:: ubuntu-debian-host-packages-nodocs.rst
>>   
>> +Additionally, on distributions other than Debian 11 and Ubuntu 22.04 (otherwise
>> +see note below), install the following package:
>> +
>> +.. code-block:: console
>> +
>> +   $ sudo apt install python3-websockets
>> +
>
> Maybe use apt-get here? I know we have one or the other across the 
> code-base. For some reason, I can't bring myself to use apt, it always 
> results in weird behaviors I don't have using apt-get on servers (I 
> don't run Debian-based on my own machines).

Yes, that's better to use here and also aligns with the rest, thanks!

>> +.. note::
>> +
>> +   On Debian 11 and Ubuntu 22.04, the requirement on the version of
>
> A bit awkward wording to me, would
>
> the minimum version for ``python3-websockets`` is not satisfied...
>
> work better?

Indeed, will rephrase

>> +   ``python3-websockets`` is not satisfied by the host distribution. This
>> +   package is used for fetching pre-built :ref:`shared state
>> +   <overview-manual/concepts:shared state>` artifacts from upstream Yocto Project
>> +   servers (see :ref:`ref-fragments-core-yocto-sstate-mirror-cdn` for more
>> +   information).
>> +
>> +   In order to use this feature, you can get the correct version of
>> +   ``python3-websockets`` by either:
>> +
>> +   -  Using a :term:`buildtools` tarball by following the
>> +      :ref:`system-requirements-buildtools` section below.
>> +
>> +   -  Installing ``python3-websockets`` using `Pip <https://pip.pypa.io/en/stable/>`__:
>> +
>> +      .. code-block:: console
>> +
>> +         $ pip install websockets
>> +
>
> websockets 9.1 supports Python 3.9 which is available in Debian 11 and 
> Ubuntu 22.04 so it'll get at least that version (it's not because a 
> newer version of a package is available on PyPI that your system can 
> install it; and the opposite is true, you may have a too new Python 
> version for the last package version available (e.g. tensorflow-lite 
> isn't compatible with Python 3.14)). Can you check what happens if the 
> user already has python3-websockets installed on the system and runs 
> this command? My hunch is it'll not get updated to >=9.1 without 
> -U/--upgrade. Also, running -U will likely break their system if any of 
> the hsot packages depend on that older version of websockets... Maybe we 
> should only be using Python packages from a virtualenv?

Maybe I can state that this it is advised to install it in a virtual environment
and avoid the possible gotchas you stated?

>>   Here are the packages needed to build Project documentation manuals:
>>   
>>   .. literalinclude:: ../tools/host_packages_scripts/ubuntu_docs.sh
>> diff --git a/documentation/tools/host_packages_scripts/fedora_essential.sh b/documentation/tools/host_packages_scripts/fedora_essential.sh
>> index 99e5d2c0b..55b8b704b 100644
>> --- a/documentation/tools/host_packages_scripts/fedora_essential.sh
>> +++ b/documentation/tools/host_packages_scripts/fedora_essential.sh
>> @@ -1 +1 @@
>> -sudo dnf install bzip2 ccache chrpath cpio cpp diffstat diffutils file findutils gawk gcc gcc-c++ git glibc-devel glibc-langpack-en gzip hostname libacl make patch perl perl-Data-Dumper perl-File-Compare perl-File-Copy perl-FindBin perl-Text-ParseWords perl-Thread-Queue perl-bignum perl-locale python python3 python3-GitPython python3-jinja2 python3-pexpect python3-pip rpcgen socat tar texinfo unzip wget which xz zstd $([ $(rpm -E %fedora) -ge 42 ] && echo "util-linux-script")
>> +sudo dnf install bzip2 ccache chrpath cpio cpp diffstat diffutils file findutils gawk gcc gcc-c++ git glibc-devel glibc-langpack-en gzip hostname libacl make patch perl perl-Data-Dumper perl-File-Compare perl-File-Copy perl-FindBin perl-Text-ParseWords perl-Thread-Queue perl-bignum perl-locale python python3 python3-GitPython python3-jinja2 python3-pexpect python3-pip python3-websockets rpcgen socat tar texinfo unzip wget which xz zstd $([ $(rpm -E %fedora) -ge 42 ] && echo "util-linux-script")
>> diff --git a/documentation/tools/host_packages_scripts/opensuse_essential_16.0.sh b/documentation/tools/host_packages_scripts/opensuse_essential_16.0.sh
>> index e557ae4fb..96bdd9317 100644
>> --- a/documentation/tools/host_packages_scripts/opensuse_essential_16.0.sh
>> +++ b/documentation/tools/host_packages_scripts/opensuse_essential_16.0.sh
>> @@ -1 +1 @@
>> -sudo zypper install bzip2 chrpath diffstat gcc gcc-c++ git gzip hostname libacl1 make makeinfo patch python3 python3-GitPython python3-Jinja2 python3-curses python3-pexpect python3-pip python3-xml rpcgen socat tar wget which xz zstd
>> +sudo zypper install bzip2 chrpath diffstat gcc gcc-c++ git gzip hostname libacl1 make makeinfo patch python3 python3-GitPython python3-Jinja2 python3-curses python3-pexpect python3-pip python313-websockets python3-xml rpcgen socat tar wget which xz zstd
>
> Can you rather use python3-websockets here? 
> https://opensuse.pkgs.org/16.0/opensuse-oss/python313-websockets-14.2-160000.2.2.aarch64.rpm.html 
> says it provides and replaces python3-websockets. That should make the 
> upgrade to the next Leap version easier since I'm assuming it may switch 
> to Python 3.14 by then?

Ah good point, I did not spot that it was a provider of python3-websockets. I'll
correct that.

Thanks,
Antonin