python3-vcstool is broken with setuptools 82.0.0+ — migrate to vcs2l

[tughril]

Problem

The Docker images currently install python3-vcstool as a bootstrap tool (e.g. in ros-base, ros2/source/devel, etc.). vcstool 0.3.0 fails at runtime when setuptools 82.0.0 or later is present, because pkg_resources was removed from setuptools in that release.

Traceback (most recent call last):
  File ".../bin/vcs", line 4, in <module>
    from vcstool.commands.vcs import main
  File ".../vcstool/commands/vcs.py", line 3, in <module>
    from vcstool.commands.help import get_entrypoint
  File ".../vcstool/commands/help.py", line 4, in <module>
    from pkg_resources import load_entry_point
ModuleNotFoundError: No module named 'pkg_resources'

This breaking change was previously reported upstream at dirk-thomas/vcstool#292 and dirk-thomas/vcstool#269, but vcstool is no longer actively maintained and the fix has not been released.

Impact on these images

• Any image that includes python3-vcstool and runs on a system with setuptools >= 82.0.0 (e.g. Python 3.12 environments, Ubuntu Noble) will have a broken vcs command at runtime.
• Users relying on vcs import inside these containers to fetch workspace sources will encounter immediate failures with no obvious workaround short of downgrading setuptools.
• As Ubuntu Noble ships Python 3.12 and newer setuptools by default, this issue affects all noble-based images and will become increasingly common.

Proposed fix

Migrate from python3-vcstool to python3-vcs2l, a maintained fork available from the ROS apt repository that has already resolved this setuptools compatibility issue.

In the Dockerfile templates, replace:

python3-vcstool \

with:

python3-vcs2l \

vcs2l is a drop-in replacement that provides the same vcs CLI interface and is actively maintained.

Note: python-vcstools / python3-vcstools (used in ROS1 EOL distros) is a separate package and is not affected by this issue.

References

• dirk-thomas/vcstool#292 — upstream bug report
• dirk-thomas/vcstool#269 — original deprecation warning
• ros-infrastructure/vcs2l#4 — fix in vcs2l