CATKIN_LINT(1)

📦

version 1.6.25 · 3 versions

1.6.25 · debian trixie (latest)
1.6.16 · ubuntu jammy
1.6.22 · debian bookworm, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 CATKIN_LINT(1) — the `catkin_lint` manual, bestie edition 💖

okay so picture this: it's a Robot OS situation, and you've got a catkin_lint command. That's the whole vibe. It's a manual page, it's long, and we're doing it in two parts, so buckle up 🎀

✨ NAME ✨

catkin_lint — check catkin packages for common errors

🌸 SYNOPSIS 🌸

catkin_lint [--config FILE] [--quiet | --no-quiet]
            [--severity-level LEVEL]
            [--notice ID] [--warning ID] [--error ID]
            [--ignore ID] [--show-ignored]
            [--strict | --no-strict]
            [--pkg PKG] [--skip-pkg PKG]
            [--package-path PATH] [--skip-path MATCH]
            [--rosdistro DISTRO] [--offline] [--no-offline]
            [--rosdep-cache-path PATH]
            [--resolve-env | --no-resolve-env]
            [--output FORMAT | --text | --explain | --xml | --json]
            [--color MODE]
            [PATH [PATH ...]]

💅 DESCRIPTION 💅

So catkin_lint is out here checking package configurations for the catkin build system of ROS. It does a static analysis of the "package.xml" and "CMakeLists.txt" files in your package, and it will detect and report a bunch of common problems. no cap, it's just reading your files and judging (lovingly) 🫶

All diagnosed problems come in one of three possible severities:

Errors are severe enough to break the build and/or produce unintended side effects. Usually, they violate the rules outlined in the catkin manual. 😭 these are the ones you actually have to fix.
Warnings are potential errors which may indicate a bug in your package but may be justified for reasons catkin_lint cannot discern. Constructs which trigger a warning can usually be modified in a way that is functionally equivalent but more robust. like, it's giving "suspicious but maybe fine" energy.
Notices are issues which are not objectionable from a technical view point but should be addressed to improve the quality of the package. Many notices highlight violations of the recommendations and best practises from the catkin manual. 💅 the glow-up suggestions.

👑 OPTIONS 👑

--config FILE — Read configuration settings from FILE. This option can be used multiple times. See "CONFIGURATION FILE FORMAT" for details. stack them configs, bestie ✨
--quiet, -q — Suppress all outputs expect for the detected problems, in particular, do not show the summary at the end. just the tea, none of the small talk.
--no-quiet — Show a summary of the findings at the end. This is the default setting. (yes bestie, the default, so if you never touched anything, this is what you're getting)
--severity-level LEVEL, -W LEVEL — Choose the severity level for diagnostic output. Level 0 displays errors only, level 1 displays errors and warnings, and level 2 displays everything. The default setting is -W1. 🎚️ pick your chaos level.
--notice ID, --warning ID, --error ID — Override the default severity of certain problems. See "PROBLEM IDS" for details on the available IDs. you get to promote or demote problems, main character energy fr.
--ignore ID — Ignore a problem. This is mostly useful to work around a known bug in catkin_lint, because problems tend to not go away if you ignore them. See "PROBLEM IDS" for details on the available IDs. 🙈 (and yes, that caveat is real — ignoring is NOT fixing, it's just looking away)
--show-ignored — Show all problems you ignored. Use this if an ignored problem did not go away, but you forgot which one. we love a receipts moment 💀
--strict — Treat any reported problem as a fatal error. Some people use the option to enforce that warnings get fixed, too. You can also combine this with -W2 to turn even notices into errors, if you are exceptionally pedantic and/or have a high pain tolerance. 😭🔥 you've been warned, that's a lot of pain tolerance.
--no-strict — This will undo the effects of your rash decision to put "strict=yes" in your configuration file. This is also the default setting. we've all been there, no judgement 🫶
--pkg PKG — Check the package PKG for problems. The package must be in the ROS package search path.
--skip-pkg PKG — Skip the package PKG when processing a package subtree. The package will not be linted, but it will be treated as a known package for dependency resolutions. so it still counts as existing, it just doesn't get the vibe check 💅
--package-path PATH[:PATH[...]] — Add one or more additional locations to the ROS package search path. Separate multiple locations with ":". catkin_lint will use this path list and the ROS_PACKAGE_PATH environment variable to resolve the --pkg option and dependencies of linted packages.
--skip-path MATCH — Skip packages if their location contains MATCH. No wildcards or pattern matching allowed, only proper substrings are recognized. substring only, bestie, don't get fancy ✨
--rosdistro DISTRO — Assume that all packages are supposed to work with the ROS distribution DISTRO. By default, this value is taken from the ROS_DISTRO environment variable. catkin_lint will use this to query the ROS database for packages which are not locally installed.
--offline — Forbid metadata queries to the ROS package index. This will disable certain diagnostics which rely on knowing details about all package dependencies. Metadata queries are not needed for packages which can be found locally through the ROS package search path. airplane mode but for package metadata 🦋
--no-offline — Allow metadata queries to the ROS package index. This is the default.
--rosdep-cache-path PATH — Override the default location of the rosdep sources cache. This option has the same effect as setting the ROSDEP_CACHE_PATH environment variable.
--resolve-env — Resolve environment variables $ENV{} in CMake scripts. By default, catkin_lint will treat all environment variables like empty strings and issue a warning.
--no-resolve-env — Do not resolve environment variables $ENV{} in CMake scripts and issue a warning if they are used. This is the default.
--output FORMAT — Select the output format for the diagnosed problems. Valid output formats are text, explain, json, and xml. See "OUTPUT FORMATS" for more details.
--text, --explain, --json, --xml — These are deprecated aliases for --output FORMAT. 💀 deprecated, so like, they work, but we're side-eyeing them.
--color MODE — Configure the colorization of the text and explain output formats. The default mode is auto, which will use ANSI colors if catkin_lint detects a terminal as output. The modes always and never will override the detection and output ANSI colors always or never, respectively. 🌈 pretty terminal colors, iconic.

🎀 OUTPUT FORMATS 🎀

catkin_lint supports a variety of output formats as argument for the --output option:

text — This is the default format, which outputs a short, human-readable description of all problems.
explain — This is an extended text format, which will show an additional explanation when a problem type occurs for the first time. It will also mention the message ID which you need to change the severity or ignore a problem. 🔍 this is the one that actually teaches you stuff, obsessed.
json — Outputs all problems in JSON format.
xml — Outputs all problems in XML format.

🌈 ENVIRONMENT 🌈

catkin_lint uses ROS_PACKAGE_PATH to find locally available packages and ROS_DISTRO to determine the installed ROS distribution when querying the ROS package index or the rosdep database. All other environment variables will be ignored, unless catkin_lint is instructed to resolve them in CMake scripts by --resolve-env.

⭐ RETURN VALUES ⭐

0 — All packages were linted successfully and no errors occurred. 🎉 slay.
1 — An error occurred.
66 — No packages found.

(part 1 done bestie, more coming — don't go anywhere) 💖

✨ CONFIGURATION FILE FORMAT ✨

Okay so bestie, catkin_lint is obsessed with config files. It looks for configuration options in these exact places, in this order (no cap):

Files explicitly specified using --config
.catkin_lint files in all locations from ROS_PACKAGE_PATH
$XDG_CONFIG_HOME/catkin_lint
~/.config/catkin_lint if XDG_CONFIG_HOME is unset or empty
~/.catkin_lint

Then it reads all available config files and merges them into one single configuration. Earlier entries in the list above will take precedence if conflicting options are found. Command line arguments will override any configuration file setting. Config files are in an INI-style format with one or more sections in it. Slay.

🌸 [catkin_lint] section 🌸

The main section is called [catkin_lint] and it takes these catkin_lint-specific options:

color = auto | never | always — Determine output colorization mode. The default setting auto will enable colorization if and only if standard output is connected to terminal. The modes always and never will override the detection and output ANSI colors always or never, respectively. 💅
offline = no | yes — Allow or forbid metadata queries to the ROS package index. This will disable certain diagnostics which rely on knowing details about all package dependencies. Metadata queries are not needed for packages which can be found locally through the ROS package search path. The default setting is no.
output = text | explain | json | xml — Select the output format for problem reports. See "OUTPUT FORMATS" for details. The default setting is text.
package_path = PATH[:PATH[...]] — Prepend the specified PATHs to ROS_PACKAGE_PATH in order to find locally available packages and/or package dependencies.
quiet = no | yes — Select output verbosity. The default setting no allows catkin_lint to print some additional information to standard error, such as a final summary of all detected problems.
resolve_env = no | yes — Allow or forbid resolution of environment variables. The default setting no lets catkin_lint ignore environment variables and issue a warning whenever a CMake command references the environment using $ENV{}.
rosdistro = DISTRO — Assume that all packages are supposed to work with the ROS distribution DISTRO. By default, this value is taken from the ROS_DISTRO environment variable. catkin_lint will use this to query the ROS database for packages which are not locally installed.
rosdep_cache_path = PATH — Override the default location of the rosdep sources cache. This option has the same effect as setting the ROSDEP_CACHE_PATH environment variable.
severity_level = 0 | 1 | 2 — Choose the severity level for diagnostic output. Level 0 displays errors only, level 1 displays errors and warnings, and level 2 displays everything. The default setting is 1.
strict = no | yes — In strict mode, catkin_lint will treat every reported problem as error and return with exit code 1 (see "RETURN VALUES"). By default, warnings and notices are informational only. This setting is mostly interesting for automated test runs, where the exit code is evaluated. Note that ignored problems and everything hidden by the chosen severity_level will not be considered failures.

💅 Package-specific severity overrides 💅

All section names besides [catkin_lint] are interpreted as package names and will override the reported severities of problems. As a special case, the section [*] will apply to all packages. The overrides are specified in the format ID = Severity, where the severity can be one of ignore, error, warning, notice, or default. See "PROBLEM IDS" for details on the available IDs.

Unlike --strict, this gives you very fine-grained control over which problems are supposed to be fatal, so you are encouraged to integrate catkin_lint into your CI test pipeline and tune the settings in a way that fits your project. So extra, I love it.

🔥 PROBLEM IDS 🔥

You can run catkin_lint --help-problem to get a list of all problem IDs, and catkin_lint --help-problem ID for a more detailed explanation of each problem. iykyk

🌈 EXAMPLES 🌈

✨ Command line arguments ✨

catkin_lint ~/catkin_ws/src

Check all packages in ~/catkin_ws/src for problems.

catkin_lint --pkg foo --pkg bar

Check the packages foo and bar for problems, assuming that they can be found in one of the locations listed in ROS_PACKAGE_PATH.

catkin_lint --pkg foo --pkg bar --package-path ~/my_other_ws/src

Check the packages foo and bar for problems when the former assumption turned out to be false.

catkin_lint ~/catkin_ws/src --skip-path unstable

Check all packages in ~/catkin_ws/src, but skip all packages in a path that contains the string unstable.

catkin_lint ~/catkin_ws/src --skip-pkg baz

Check all packages except baz in ~/catkin_ws/src.

🎀 Configuration file 🎀

The following configuration file will instruct catkin_lint to output its results in JSON format, ignore any problems with unknown packages (except in the package foo), and elevate the notice about unsorted lists to a warning for all packages (including foo):

[catkin_lint]
output = json
quiet = yes

[*]
unknown_package = ignore
unsorted_list = warning

[foo]
unknown_package = default

🌟 REFERENCES 🌟

https://fkie.github.io/catkin_lint/

💖 That's the whole vibe, bestie! This manual page is from catkin_lint version 1.6.25, dated 2024-09-24. Now go lint your heart out! 💖

📦 where this page comes from

debian trixie: catkin-lint 1.6.25-1 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms