catkin clean – Clean Build Products

The clean verb makes it easier and safer to clean various products of a catkin workspace. In addition to removing entire build, devel, and install spaces, it also gives you more fine-grained control over removing just parts of these directories.

The clean verb is context-aware, but in order to work, it must be given the path to an initialized catkin workspace, or called from a path contained in an initialized catkin workspace.

Space Cleaning

For any configuration, any of the active profile’s spaces can be cleaned entirely. This includes any of the top-level directories which are configured for a given profile. See the full command line interface for specifying specific spaces to clean.

To clean all of the spaces for a given profile, you can call the clean verb without arguments:

catkin clean

When running this command, catkin will prompt you to confirm that you want to delete the entire directories:

$ catkin clean
[clean] Warning: This will completely remove the following directories. (Use `--yes` to skip this check)
[clean] Log Space:     /tmp/quickstart_ws/logs
[clean] Build Space:   /tmp/quickstart_ws/build
[clean] Devel Space:   /tmp/quickstart_ws/devel

[clean] Are you sure you want to completely remove the directories listed above? [yN]:

If you want to skip this check, you can use the --yes or -y options:

$ catkin clean -y
[clean] Removing develspace: /tmp/quickstart_ws/devel
[clean] Removing buildspace: /tmp/quickstart_ws/build
[clean] Removing log space: /tmp/quickstart_ws/logs

Note

The clean verb will also ask for additional confirmation if any of the directories to be removed are outside of your workspace root. To skip this additional check, you can use the --force option.

Partial Cleaning

If a workspace is built with a linked devel space, the clean verb can be used to clean the products from individual packages. This is possible since the catkin program will symbolically link the build products into the devel space, and stores a list of these links.

Cleaning a Single Package

Cleaning a single package (or several packages) is as simple as naming them:

catkin clean PKGNAME

This will remove products from this package from the devel space, and remove its build space.

Cleaning Products from Missing Packages

Sometimes, you may disable or remove source packages from your workspace’s source space. After packages have been removed from your source space, you can automatically clean the “orphaned” products with the following command:

catkin clean --orphans

Cleaning Dependent Packages

When cleaning one package, it’s sometimes useful to also clean all of the packages which depend on it. This can prevent leftover elements from affecting the dependents. To clean a package and only the packages which depend on it, you can run the following:

catkin clean --dependents PKGNAME

Cleaning Products from All Profiles

By default, the clean operating is applied only to the active or specified profile. To apply it to all profiles, use the --all-profiles option.

Cleaning Everything

If you want to clean everything except the source space (i.e. all files and folders generated by the catkin command, you can use --deinit to “deinitialize” the workspace. This will clean all products from all packages for all profiles, as well as the profile metadata, itself. After running this, a catkin_tools workspace will need to be reinitialized to be used.

catkin clean --deinit

Full Command-Line Interface

usage: catkin clean [-h] [--workspace WORKSPACE] [--profile PROFILE]
                    [--dry-run] [--verbose] [--yes] [--force] [--all-profiles]
                    [--deinit] [-l] [-b] [-d] [-i] [--dependents] [--orphans]
                    [--setup-files]
                    [PKGNAME [PKGNAME ...]]

Deletes various products of the build verb.

optional arguments:
  -h, --help            show this help message and exit
  --workspace WORKSPACE, -w WORKSPACE
                        The path to the catkin_tools workspace or a directory
                        contained within it (default: ".")
  --profile PROFILE     The name of a config profile to use (default: active
                        profile)
  --dry-run, -n         Show the effects of the clean action without modifying
                        the workspace.
  --verbose, -v         Verbose status output.
  --yes, -y             Assume "yes" to all interactive checks.
  --force, -f           Allow cleaning files outside of the workspace root.
  --all-profiles        Apply the specified clean operation for all profiles
                        in this workspace.

Full:
  Remove everything except the source space.

  --deinit              De-initialize the workspace, delete all build profiles
                        and configuration. This will also clean subdirectories
                        for all profiles in the workspace.

Spaces:
  Clean workspace subdirectories for the selected profile.

  -l, --logs            Remove the entire log space.
  -b, --build           Remove the entire build space.
  -d, --devel           Remove the entire devel space.
  -i, --install         Remove the entire install space.

Packages:
  Clean products from specific packages in the workspace. Note that these
  options are only available in a `linked` devel space layout. These options
  will also automatically enable the --force-cmake option for the next build
  invocation.

  PKGNAME               Explicilty specify a list of specific packages to
                        clean from the build, devel, and install space.
  --dependents, --deps  Clean the packages which depend on the packages to be
                        cleaned.
  --orphans             Remove products from packages are no longer in the
                        source space. Note that this also removes packages
                        which are blacklisted or which contain `CATKIN_INGORE`
                        marker files.

Advanced:
  Clean other specific parts of the workspace.

  --setup-files         Clear the catkin-generated setup files from the devel
                        and install spaces.