{"id":4904,"library":"catkin-pkg","title":"catkin-pkg: Catkin Package Library","description":"catkin-pkg is a standalone Python library designed to support the Catkin build system, primarily used in the Robot Operating System (ROS) ecosystem. It provides functionalities for finding, introspecting, and managing Catkin packages within the file system, including parsing `package.xml` manifest files. The current version is 1.1.0, and it maintains an active development status with periodic releases.","status":"active","version":"1.1.0","language":"python","source_language":"en","source_url":"https://github.com/ros-infrastructure/catkin_pkg","tags":["ros","catkin","build-system","package-management","robotics"],"install":[{"cmd":"pip install catkin-pkg","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"Package","correct":"from catkin_pkg.package import Package"},{"note":"Import specific functions or classes directly for clarity and better tree-shaking.","wrong":"import catkin_pkg.package.parse_package","symbol":"parse_package","correct":"from catkin_pkg.package import parse_package"},{"symbol":"find_packages","correct":"from catkin_pkg.packages import find_packages"}],"quickstart":{"code":"import os\nimport tempfile\nimport shutil\nfrom pathlib import Path\nfrom catkin_pkg.packages import find_packages\n\n# Create a dummy catkin workspace for demonstration\ntemp_dir = Path(tempfile.mkdtemp())\nworkspace_path = temp_dir / \"my_catkin_ws\"\nsrc_path = workspace_path / \"src\"\nsrc_path.mkdir(parents=True, exist_ok=True)\n\n# Create a dummy package A\npkg_a_path = src_path / \"package_a\"\npkg_a_path.mkdir(exist_ok=True)\n(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>\"\"\")\n\n# Create a dummy package B depending on A\npkg_b_path = src_path / \"package_b\"\npkg_b_path.mkdir(exist_ok=True)\n(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>\"\"\")\n\n# Find and parse packages\nprint(f\"Searching for packages in: {src_path}\")\nfound_packages = find_packages(str(src_path))\n\nprint(f\"Found {len(found_packages)} packages:\")\nfor path, pkg in found_packages.items():\n    print(f\"- Path: {path}\")\n    print(f\"  Name: {pkg.name}\")\n    print(f\"  Version: {pkg.version}\")\n    print(f\"  Description: {pkg.description}\")\n    print(f\"  Dependencies:\")\n    for dep in pkg.buildtool_depends:\n        print(f\"    Buildtool: {dep.name}\")\n    for dep in pkg.depends:\n        print(f\"    Runtime/Build: {dep.name}\")\n\n# Clean up the dummy workspace\nshutil.rmtree(temp_dir)","lang":"python","description":"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."},"warnings":[{"fix":"Only 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.","message":"Do 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use a single build tool for a given workspace. If switching, perform a `catkin clean` before rebuilding, or start with a fresh workspace.","message":"Mixing 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.","severity":"gotcha","affected_versions":"All versions of Catkin tools"},{"fix":"Ensure 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.","message":"Packages 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If changes are not being picked up, try running `catkin clean --force` followed by `catkin build` to force a complete rebuild.","message":"When 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.","severity":"gotcha","affected_versions":"All versions of Catkin tools"}],"env_vars":null,"search_vec":"'1.1.0':54 'activ':59 'build':20,68 'build-system':67 'catkin':2,4,8,19,39,66 'catkin-pkg':1,7 'current':51 'design':15 'develop':60 'ecosystem':30 'file':43,49 'find':35 'function':33 'includ':45 'introspect':36 'librari':6,14 'maintain':57 'manag':38,72 'manifest':48 'oper':27 'packag':5,40,71 'package-manag':70 'package.xml':47 'pars':46 'period':63 'pkg':3,9 'primarili':22 'provid':32 'python':13 'releas':64 'robot':26,73 'ros':29,65 'standalon':12 'status':61 'support':17 'system':21,28,44,69 'use':23 'version':52 'within':41","created_at":"2026-04-12T16:45:41.531825+00:00","updated_at":"2026-04-16T01:33:04.763103+00:00","problems":[{"fix":"Ensure '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.","cause":"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.","error":"ModuleNotFoundError: No module named 'catkin_pkg'"},{"fix":"Verify 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.","cause":"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.","error":"CMake Error at ... (message): execute_process(/usr/bin/python3 ... package_xml_2_cmake.py ...) returned error code 1"},{"fix":"First, 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.","cause":"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.","error":"ImportError: No module named 'catkin_pkg.packages'"},{"fix":"Resolve 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.","cause":"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.","error":"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."},{"fix":"Inspect 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.","cause":"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.","error":"The manifest contains invalid XML: no element found: line 1, column 0"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.1.0","cli_name":"catkin_pkg","cli_version":"sh: 1: catkin_pkg: not found","type":"library","homepage":"http://wiki.ros.org/catkin_pkg","github":"https://github.com/ros-infrastructure/catkin_pkg","docs":null,"changelog":null,"pypi":"https://pypi.org/project/catkin-pkg/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}