{"id":9608,"library":"colcon-python-setup-py","title":"colcon-python-setup-py","description":"colcon-python-setup-py is an extension for the colcon build system that enables it to properly discover, configure, and build Python packages that define their metadata using a `setup.py` file. It ensures `colcon` can correctly handle Python packages, resolve their dependencies, and integrate them into a larger workspace. The current version is 0.2.9, with active development and infrequent but stable releases, typically every 3-9 months.","status":"active","version":"0.2.9","language":"en","source_language":"en","source_url":"https://github.com/colcon/colcon-python-setup-py/","tags":["colcon","ros","build-system","python","packaging","setuptools"],"install":[{"cmd":"pip install colcon-python-setup-py","lang":"bash","label":"Install colcon-python-setup-py"}],"dependencies":[{"reason":"This is a colcon extension and requires the core colcon package to function. It will not work without colcon-core installed.","package":"colcon-core","optional":false}],"imports":[],"quickstart":{"code":"# First, install colcon-core if you haven't already:\n# pip install colcon-core\n\n# Then, install the python setup.py extension:\n# pip install colcon-python-setup-py\n\n# 1. Create a colcon workspace and source directory\nmkdir -p colcon_ws/src\ncd colcon_ws/src\n\n# 2. Create a simple Python package with setup.py\nmkdir my_python_pkg\ncd my_python_pkg\n\n# Create setup.py\ncat <<EOF > setup.py\nfrom setuptools import setup, find_packages\n\nsetup(\n    name='my_python_pkg',\n    version='0.0.1',\n    packages=find_packages(),\n    install_requires=[],\n    zip_safe=True,\n    maintainer='Your Name',\n    maintainer_email='your.email@example.com',\n    description='A sample Python package for colcon.',\n    license='Apache-2.0',\n)\nEOF\n\n# Create a simple Python module\nmkdir my_python_pkg\ncat <<EOF > my_python_pkg/__init__.py\ndef hello_world():\n    return \"Hello from colcon-python-setup-py!\"\nEOF\n\n# 3. Go back to the workspace root and build\ncd ../..\ncolcon build\n\necho \"\\nBuild complete. Check 'colcon_ws/install' for the installed package.\"\n","lang":"bash","description":"This quickstart demonstrates how to set up a `colcon` workspace, create a basic Python package with a `setup.py` file, and then use `colcon build` to compile and install it. The `colcon-python-setup-py` extension automatically detects the `setup.py` file and uses it to build the package."},"warnings":[{"fix":"Ensure your package has a `setup.py` file. If migrating to `pyproject.toml`, consider other `colcon` extensions or ensure `pyproject.toml` delegates to `setup.py` or uses a compatible build backend.","message":"This extension explicitly targets Python packages using `setup.py` for metadata. If your Python package uses `pyproject.toml` (e.g., with Poetry, Hatch, or modern setuptools build backends), this extension will not be used. colcon might try to use a different build type, or you may need another colcon extension like `colcon-python-poetry`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Before installing or using `colcon-python-setup-py`, make sure `colcon-core` is installed: `pip install colcon-core`.","message":"The `colcon-python-setup-py` package is an extension and requires the `colcon-core` package to be installed separately. It will not function on its own without the core `colcon` CLI tool.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully review your `setup.py` according to `setuptools` documentation. Use `python setup.py install --prefix /tmp/test_install` to test the `setup.py` in isolation.","message":"Issues within the `setup.py` file itself (e.g., incorrect `install_requires`, malformed `entry_points`, missing `find_packages()`) can lead to build failures or runtime errors. Debugging these requires understanding `setuptools`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install `colcon-core`: `pip install colcon-core`.","cause":"The `colcon-core` package, which provides the `colcon` executable, is not installed or not in your PATH.","error":"colcon: command not found"},{"fix":"Verify that `colcon-python-setup-py` is installed (`pip show colcon-python-setup-py`). Ensure your package's `setup.py` file is correctly located at the root of your package directory within the `src` folder. Check for typos or incorrect file permissions.","cause":"colcon could not detect a `setup.py` file, or there's a conflict with another build type, or the `colcon-python-setup-py` extension is not installed.","error":"Could not find a build type for the package 'your_package_name'"},{"fix":"Add the missing dependency to the `install_requires` list in your `setup.py`. If it's a system dependency, ensure it's installed on your system. If the package has complex build steps, consider adding a custom `build` hook if necessary.","cause":"A Python dependency required by your package is not specified in `install_requires` within your `setup.py`, or it failed to install during the colcon build process (often due to missing system dependencies or conflicts).","error":"ModuleNotFoundError: No module named 'your_dependency_name' during colcon build"}]}