Skip to content

docs: discourage main-subpackage name collisions for multiple outputs: in define-metadata.rst #5767

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jezdez merged 2 commits into from
Apr 29, 2026
Merged

docs: discourage main-subpackage name collisions for multiple outputs: in define-metadata.rst #5767

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a38faed
docs: discourage main-subpackage name collisions for multiple `output…
dlaehnemann Aug 4, 2025
2552d7b
Merge branch 'main' into patch-1
dlaehnemann Dec 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 10 additions & 6 deletions docs/source/resources/define-metadata.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1377,7 +1377,9 @@ in conda-build 2.1.0.
default packaging behavior of conda-build is bypassed. In other
words, if any subpackage is specified, then you do not get the
normal top-level build for this recipe without explicitly
defining a subpackage for it. This is an alternative to the
defining a subpackage for it. But having a subpackage with the same
name as the top-level should be avoided, as this leads to a number
of unintended and hard to understand bugs. This is an alternative to the
existing behavior, not an addition to it. For more information,
see :ref:`implicit_metapackages`. Each output may have its own version and
requirements. Additionally, subpackages may impose downstream pinning similarly
Expand Down Expand Up @@ -1538,11 +1540,13 @@ Implicit metapackages

When viewing the top-level package as a collection of smaller
subpackages, it may be convenient to define the top-level
package as a composition of several subpackages. If you do this
and you do not define a subpackage name that matches the
top-level package/name, conda-build creates a metapackage for
you. This metapackage has runtime requirements drawn from its
dependency subpackages, for the sake of accurate build strings.
package as a composition of several subpackages. If you do this,
do not define a subpackage name that matches the top-level
package/name, as this will lead to a number of unintended and
hard to understand bugs. Also, if you avoid such a name clash,
conda-build creates a metapackage for you. This metapackage
has runtime requirements drawn from its dependency subpackages,
for the sake of accurate build strings.

EXAMPLE: In this example, a metapackage for ``subpackage-example``
will be created. It will have runtime dependencies on
Expand Down