Install & Compatibility
Where this runs
tested against v1.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.370s · 25.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 0.316s · 26MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Package
✓ from catkin_pkg.package import Package
parse_package
✓ from catkin_pkg.package import parse_package
✗ import catkin_pkg.package.parse_package
Import specific functions or classes directly for clarity and better tree-shaking.
find_packages
✓ from catkin_pkg.packages import find_packages
This quickstart demonstrates how to use `catkin_pkg` to find and introspect Catkin packages within a directory. It creates a temporary directory simulating a Catkin workspace, adds two dummy packages with `package.xml` files, and then uses `find_packages` to locate and parse them, printing out key metadata for each.
import os
import tempfile
import shutil
from pathlib import Path
from catkin_pkg.packages import find_packages
# Create a dummy catkin workspace for demonstration
temp_dir = Path(tempfile.mkdtemp())
workspace_path = temp_dir / "my_catkin_ws"
src_path = workspace_path / "src"
src_path.mkdir(parents=True, exist_ok=True)
# Create a dummy package A
pkg_a_path = src_path / "package_a"
pkg_a_path.mkdir(exist_ok=True)
(pkg_a_path / "package.xml").write_text("""<?xml version=\"1.0\"?>\n<package format=\"2\">\n <name>package_a</name>\n <version>0.1.0</version>\n <description>A dummy package A</description>\n <maintainer email=\"user@example.com\">User Name</maintainer>\n <license>MIT</license>\n <buildtool_depend>catkin</buildtool_depend>\n <depend>python3-catkin-pkg</depend>\n</package>""")
# Create a dummy package B depending on A
pkg_b_path = src_path / "package_b"
pkg_b_path.mkdir(exist_ok=True)
(pkg_b_path / "package.xml").write_text("""<?xml version=\"1.0\"?>\n<package format=\"2\">\n <name>package_b</name>\n <version>0.1.0</version>\n <description>A dummy package B</description>\n <maintainer email=\"user@example.com\">User Name</maintainer>\n <license>MIT</license>\n <buildtool_depend>catkin</buildtool_depend>\n <depend>package_a</depend>\n</package>""")
# Find and parse packages
print(f"Searching for packages in: {src_path}")
found_packages = find_packages(str(src_path))
print(f"Found {len(found_packages)} packages:")
for path, pkg in found_packages.items():
print(f"- Path: {path}")
print(f" Name: {pkg.name}")
print(f" Version: {pkg.version}")
print(f" Description: {pkg.description}")
print(f" Dependencies:")
for dep in pkg.buildtool_depends:
print(f" Buildtool: {dep.name}")
for dep in pkg.depends:
print(f" Runtime/Build: {dep.name}")
# Clean up the dummy workspace
shutil.rmtree(temp_dir)
catkin_pkg --version
Debug
Known issues
gotchaDo not install `catkin-pkg-modules` from PyPI. The `catkin-pkg-modules` package exists on Debian/Ubuntu for specific Python 2/3 co-installation scenarios, but for pip installations, `catkin-pkg` provides all necessary Python modules. Installing `catkin-pkg-modules` via pip is unnecessary and was previously a duplicated effort.fixOnly install `catkin-pkg` via pip. If encountering issues related to `catkin-pkg-modules`, ensure you are not mixing system-installed (apt) and pip-installed Python packages for Catkin.
affects: All versions
gotchaMixing Catkin build tools (e.g., building with `catkin_make` or `catkin_make_isolated` and then `catkin build` from `catkin_tools`) can lead to an 'Inconsistent Environment' and unpredictable build failures due to cached configuration differences.fixAlways use a single build tool for a given workspace. If switching, perform a `catkin clean` before rebuilding, or start with a fresh workspace.
affects: All versions of Catkin tools
gotchaPackages with incorrect or implicitly satisfied dependencies in their `package.xml` files (e.g., relying on side-effects of other packages in the same workspace) can fail to build or link correctly when using stricter build tools or migrating workspaces. Common errors include 'Unknown CMake command “catkin_package”' or missing headers/libraries.fixEnsure all direct dependencies are explicitly listed in `package.xml` and `CMakeLists.txt`. Verify packages build correctly in isolation before integrating them into a larger workspace.
affects: All versions
gotchaWhen using `catkin build` (part of `catkin_tools`), sometimes local changes to source files are not detected, leading to stale executables or libraries. This is often a caching issue in the build system.fixIf changes are not being picked up, try running `catkin clean --force` followed by `catkin build` to force a complete rebuild.
affects: All versions of Catkin tools
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'catkin_pkg'
The Python interpreter being used by your environment or build system cannot find the 'catkin_pkg' library, often due to an incorrect Python environment, missing installation, or PATH issues, especially when using ROS or multiple Python versions like Anaconda.
fixEnsure 'catkin_pkg' is installed for the active Python environment: `pip install catkin_pkg` or `sudo apt install python3-catkin-pkg`. If using ROS, ensure your ROS setup script (`source /opt/ros/<distro>/setup.bash`) is sourced and that `ROS_PACKAGE_PATH` includes necessary directories. If using Anaconda, consider deactivating the conda environment or installing `catkin_pkg` within the conda environment.
CMake Error at ... (message): execute_process(/usr/bin/python3 ... package_xml_2_cmake.py ...) returned error code 1
This error typically occurs during a Catkin or ROS build when CMake tries to execute a Python script (`package_xml_2_cmake.py`) to process `package.xml` files, but the Python command fails. The most common underlying reason is the Python interpreter not being able to import `catkin_pkg` (as indicated by an accompanying `ModuleNotFoundError` in the logs) or an incorrect Python executable being called.
fixVerify that `catkin_pkg` is installed for the Python interpreter identified in the error path. If multiple Python versions exist, ensure the correct one is prioritized in your PATH or explicitly specified. Reinstall `python3-catkin-pkg` using your system's package manager (`sudo apt install --reinstall python3-catkin-pkg`) or `pip install catkin_pkg` in the relevant Python environment.
ImportError: No module named 'catkin_pkg.packages'
This is a specific `ModuleNotFoundError` indicating that the `packages` submodule within `catkin_pkg` cannot be found. This suggests that while `catkin_pkg` might be installed, its internal structure might be corrupted, or an older/incompatible version is present, or the Python environment is still not correctly configured to fully access the installed `catkin_pkg` components.
fixFirst, try reinstalling `catkin_pkg` to ensure all submodules are correctly in place: `pip install --upgrade --force-reinstall catkin_pkg` or `sudo apt install --reinstall python3-catkin-pkg`. Ensure your Python environment is clean and correctly activated, especially if working with virtual environments or ROS setups.
The following packages have unmet dependencies: catkin : Depends: python3-catkin-pkg (...) but it is not going to be installed E: Unable to correct problems, you have held broken packages.
This error occurs during system package installation (e.g., using `apt`) when there are conflicts or unmet dependencies involving `catkin` and `python3-catkin-pkg`. This can happen when mixing packages from different sources (e.g., official Ubuntu/Debian repositories with ROS repositories) or if other packages are 'held' by the package manager, preventing `python3-catkin-pkg` from being installed or upgraded.
fixResolve package conflicts by carefully checking your `apt` sources.list and prioritizing official ROS repositories if applicable. Try `sudo apt update && sudo apt upgrade` to update all packages. If specific packages are held, try `sudo apt install python3-catkin-pkg` directly, and if it suggests holding other packages, investigate those conflicts. Avoid mixing `pip` installations of `catkin_pkg` with system-level `apt` installations unless in isolated virtual environments.
The manifest contains invalid XML: no element found: line 1, column 0
This error indicates that `catkin_pkg` (or the underlying XML parser it uses) is attempting to read a `package.xml` file that is empty or severely malformed, often at the very beginning of the file.
fixInspect the `package.xml` file in question to ensure it is not empty and contains valid XML syntax, starting with `<?xml version="1.0"?>` and having a root `<package>` element. Use `catkin_create_pkg` to generate a valid `package.xml` template for new packages.
Upgrade
Version history
1.1.0latest on PyPI · released Sep 10, 2025
Audit
Dependencies
No dependency data recorded yet.