I use org-id to automatically create ID.

For instance in an org mode file: File_A.org

* File_A section

I type C-c l that create an id

* File_A section
  :ID:       21588817-03d2-4000-8d37-43649499eff6

Then I want to include File_A section in another file, File_B.org,

(in File_B.org)

#+INCLUDE: "file_A.org::#21588817-03d2-4000-8d37-43649499eff6"

However, this does not work (C-c ' does not follow the link).

To make it works I have to manually add a redundant "CUSTOM_ID" property.

* File_A section
  :ID:       21588817-03d2-4000-8d37-43649499eff6
  :CUSTOM_ID: 21588817-03d2-4000-8d37-43649499eff6

I am confused by the role of :ID: and :CUSTOM_ID:...

Why on one side Org-Mode's #+INCLUDE:s follow :CUSTOM_ID: (official doc) and on the other side, org-id's links (C-c l and C-c C-l) use :ID: (official org-mode/org-id.el file)?

Ideally I do not want to have a redundant and manually added:CUSTOM_ID: every time I use #+INCLUDE:. My question: is there a clean way to #+INCLUDE: a section using :ID: and not :CUSTOM_ID:?

Update: on Apr 29 2022 the problem is still present (org mode version 9.5.2)


1 Answer 1


Forget about ID, used to generate unique identifiers (likely to be used by downstream libraries, not users), and use CUSTOM_ID.

To insert it, forget about C-c l and use C-c C-x p to set a property. You can then select CUSTOM_ID. You can also include a heading directly by it's name:

#+INCLUDE: file.org::*File_A section

When giving your headings CUSTOM_IDs, prefer names that make sense for you, so that you can make sense of the heading in the includer file.

  • 1
    Thanks for your answer. I understand your point, however I like :ID: because I think that they are more robust (org-id keeps a ID database). For instance if I rename File_A.org to something_else.org my links will always work (Emacs scan the agenda files). This is not the case if my links explicitly use the file name (CUSTOM_ID case). Nov 27, 2018 at 8:36
  • If the heading subtree is archived, links to its CUSTOM_ID will fail. If you change the heading by editing to something else, the #+INCLUDE: file.org::*File_A section will fail too.
    – Jason
    Feb 23, 2020 at 14:57
  • How would one jump to the custom id? M-x search-forward CUSTOM_ID: value (or backward) is cumbersome...
    – user19777
    Jan 22, 2023 at 2:41

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.