ROS Resources: Documentation | Support | Discussion Forum | Service Status | Q&A

File naming convention "rosinstall" misleading?



(I can’t find a better channel but please feel free to move this to a more appropriate one.)

I’m wondering if using rosinstall still makes sense as the naming convention of the files that are typically passed to wstool. Reason being:

  • Those files together with wstool don’t install, instead they are used for downloading repositories IMO.
  • By wstool being ROS-independent tool, those files together with wstool can be used for downloading non-ROS repos.
  • After all, the are the files that are passed to wstool. I assume rosinstall came from the tool that was previously used.
    • So using something like “wstool” makes more sense, e.g. .wstool?

(Note: my experience is highly wstool-intensive. I’m not aware of any other active usecase of rosinstall files.)

I suggest updating documentation incl. tutorials, but the core document of his naming is REP 126. I can open an MR to update the rep that if that makes sense.
This is just about a convention so I don’t think existing usecases get affected even if we change the REP etc.

I’ve seen some experienced engineers who recently started working in ROS-related projects getting confused due to this.


wstool has assumptions about workspaces (hence the name). It also requires one to operate on (or initialise one). From the usage doc string:

wstool is a command to manipulate ROS workspaces. wstool replaces its predecessor rosws.

Successor to wstool is vcstool, which completely decouples “downloading repositories” from workspace management. Part of the rationale would seem to be exactly the points you raise.

vcstool uses .repos files (to avoid the confusion with ROS) and only supports .rosinstall files for convenience / historical reasons.


You were already part of that discussion 5 years ago:


@tkruse Thank you for the headsup. Indeed I was it looks like. I’ll continue there if I want to.

I was not aware of vcstool. Thank you!

Is there a plan for vcstool to be an official “successor” to wstool? I can’t find any announcement for vcstool yet with regard to wstool. Tutorials still use wstool AFAICT (e.g.


No, there is no plan to do so. The existing solution using wstool works perfectly fine and changing all documentation referencing it is a significant effort.

Both tools can be used for the task and it is mostly a personal preference which one you choose.

The ROS 2 instructions all use vcstool just because they have been written after vcstool was created (which is already six years ago).


This has been discussed in several places in the past, such as here:!topic/ros-sig-ng-ros/wwKMRBov-7c
or here: vcstools/wstool#19 (at the bottom)