Skip to content

warnings for local-recipes-index #4297

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

Open
memsharded wants to merge 2 commits into
base: develop2
Choose a base branch
from
Open

warnings for local-recipes-index #4297

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1d80ef3
warnings for local-recipes-index
memsharded Nov 5, 2025
77d5dcc
Merge branch 'develop2' into feature/local_recipes_index_warnings
czoido Jul 21, 2026
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
25 changes: 23 additions & 2 deletions devops/devops_local_recipes_index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,26 @@ This setup is particularly useful for:
:ref:`setup_local_recipes_index`.


.. warning::

Using the ``local-recipes-index`` feature from a fork of ``conan-center-index`` Github repository,
without using a package server or relying on the ConanCenter package server can easily result in
missing dependencies due to old versions being removed by upstream ``conan-center-index``. The
recommendations are:
Comment on lines +23 to +26

@jcar87 jcar87 Jul 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would probably tweak wording to make it more "generic" in terms of explaining the pitfalls, but more specific in terms of what happens with Conan Center.

Some suggestions:

  • Mention explicity that the git repository at conan-center-index's main purpose is to feed into the conancenter remote, and the ability to use it as a local-recipes-index is not a goal.
  • Remove "building binaries from a private conan-center-index fork" from the paragraph above - and instead mention something like "test changes in multiple recipes together without exporting them before hand" (which from memory, I believe was one of the intended uses of local-recipes-index when it comes to operating a fork)
  • Clarify, very explicitly, that unlike a remote Conan server, local-recipes-index does not support recipe revisions, but instead the current branch is a snapshot of all versions and revisions visible. This is already mentioned down below, but may be good to mention it here again
  • Reword, that when using a local-recipes-index with a fork of conan-center-index, users must be careful in the two following scenarios:
    • bringing changes from upstream (git pull, git merge master, git rebase master etc) - because versions they rely on may no longer be exportable from master. Here the best mitigation is just to ensure the versions needed by the user are always in the repo, for example, they can always add their versions to a different subfolder (e.g. something other than "all") - which will minimise merge conflicts as the only potential change is "config.yml" in this scenario
  • when using the conancenter remote alongside local-recipes-index, you have two repositories that potentially export the same versions. This may be intentional or not - users need exercise care.


- Use a package server to store your recipes and binaries built from your fork, and use it to resolve
dependencies.
Comment on lines +28 to +29

@jcar87 jcar87 Jul 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since it is not possible to upload binary packages to a remote without also uploading the recipes, I would probably just leave this whole section out, as it essential boils down to "if you need binaries, you need a server" therefore, using local-recipes-index AND needing to configure a remote, it is not entirely clear in which scenario local-recipes-index offers an advantage.

- If not using a package server, at least consider adding ``conancenter`` as remote besides your
``local-recipes-index``, possibly with the ``recipes-only`` argument enabled, to be able to fetch
those older versions removed from the source from it.
- If you are not using a server, then it becomes necessary to move forward with the ``local-recipes-index``
source repository. If a version is removed, the requirements to that old version must be updated to
existing versions.
- Another alternative is managing your fork accordingly, to avoid removals, not merging from upstream,
applying only selective patches.



Building Binaries from a private `conan-center-index` fork
----------------------------------------------------------

Expand Down Expand Up @@ -229,8 +249,9 @@ Several important points should be considered when using this new feature:
packages for regular use.

- Also, note that a server remote can retain a history of changes storing multiple recipe
revisions. In contrast, a `local-recipes-index` remote can only represent a single
snapshot at any given time.
versions and revisions. In contrast, a `local-recipes-index` remote can only represent a single
snapshot at any given time. That means that it will be impossible to use or resolve to older
recipe revisions or to old versions that have been removed from the source repository.

- ConanCenter does not use ``python-requires``, as this is a mechanism more intended for
first-party packages. Using ``python-requires`` in a ``local-recipes-index`` repository
Expand Down
9 changes: 9 additions & 0 deletions tutorial/conan_repositories/setup_local_recipes_index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,15 @@ upload packages or store binaries. The purpose of this remote is:
For detailed setup and usage instructions, see the dedicated section in the Conan DevOps
Guide :ref:`devops_local_recipes_index`.


.. warning::

Recall that the ``local-recipes-index`` is a "source" repository, and as such it has
several limitations with respect to full package servers. Please read carefully the
instructions and warnings in :ref:`devops_local_recipes_index` before using this
type of remote.


Setup
-----

Expand Down