This is a two part question having to do with link rot.

  1. Does org-mode provide any functionality for validating hyperlinks, especially local ones? This could be used to combat link rot after the fact.

  2. Even better, does org provide functionality so that if I rename a file in dired, it will update affected files? This could prevent some kinds of link rot before it happens, at least for local files.

4 Answers 4


For part 1, I didn't find anything built-in. The following function will provide a list of broken links in the minibuffer. I've tested it on some simple examples, but far from exhaustively.

(defun check-bit-rot ()
  "Searches current buffer for file: links, and reports the broken ones."
    (let (file-links)
      (while (re-search-forward org-link-bracket-re nil t)
        (if (string= "file:" (match-string-no-properties 1))
            (if (not (file-exists-p (match-string-no-properties 3)))
                (setq file-links
                      (cons (match-string-no-properties 0)
       (concat "Warning: broken links in this file:\n"
               (mapconcat #'identity file-links "\n"))))))
  • 2
    Do you think org-bracket-link-analytic-regexp would help pick apart Org links? Seems like it was created for tasks just like this one. Dec 16, 2014 at 2:23
  • @Constantine yes, thanks! Didn't know about that one.
    – Tyler
    Dec 16, 2014 at 2:45
  • Nice. Two possible add-on ideas: (1) add some marking text to bad links to promote discovery via search and/or highlighting; (2) bookmark the bad links.
    – David J.
    Dec 16, 2014 at 3:08
  • Idea (3) make this into a flycheck checker, and the in-buffer highlighting will be done for you.
    – Malabarba
    Dec 16, 2014 at 10:16
  • Interesting suggestions. I'll dig into it when time permits over the holiday.
    – Tyler
    Dec 17, 2014 at 1:52

Since Org 9.0 you can run the org-lint function which, among other things, checks for broken local links.

  • How can you narrow down org-lint output to only display broken links?
    – GNUmon
    Jun 25, 2023 at 11:48

I wrote a Python script https://github.com/cashTangoTangoCash/orgFixLinks that attempts to repair broken links to local files, within one or more org files on a local drive in the Ubuntu OS. It is certainly an amateur command line script, but might be worth playing with. There is a GitHub wiki that provides a degree of documentation: https://github.com/cashTangoTangoCash/orgFixLinks/wiki. Please check the warnings in the README.

I'm sorry that this Python script is not a part of Org, but completely separate/stand-alone. I hope no-one is bothered that I am not answering the question of the OP directly; I just thought someone might like playing with the Python script.

  (setq org-id-link-to-org-use-id 'create-if-interactive-and-no-custom-id)
  • use org-store-link to store a link (works on non-org files, too)
  • use org-insert-link to insert the stored link

If you want more features:

  • org-super-links
  • org-roam

Update: org needs some kind of config to actually find the IDs after renames.

One way to do this is to:

  • Install org-roam
  • Set org-roam-directory to the root of all your files
  • Run (org-roam-db-build-cache), (org-roam-db-update)

Another solution is to set org-id-extra-files to all the org files you have.

  • 1
    It's unclear how this answers the OP's question. Can you please explain?
    – Dan
    May 10, 2021 at 13:08
  • @Dan It uses UUIDs instead of file paths to create links, and UUIDs don't rot.
    – HappyFace
    May 10, 2021 at 13:11
  • 1
    It's still unclear how your post answers the OP's question. I've tried your solution briefly by moving files, and the links do not work.
    – Dan
    May 10, 2021 at 13:17
  • @Dan You're right. I myself am new to this. I think we need to do some config for org to find the IDs. I'll edit the answer when I figure out the trick.
    – HappyFace
    May 10, 2021 at 13:31
  • 1
    @Tyler I don't really know, unfortunately. I came to this question looking for answers, and posted what I pieced together.
    – HappyFace
    May 11, 2021 at 14:20

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.