This is the official manual for the latest Org-mode release.
:cache header argument is for caching results of evaluating code
blocks. Caching results can avoid re-evaluating ‘src’ code blocks that
have not changed since the previous run. To benefit from the cache and avoid
redundant evaluations, the source block must have a result already present in
the buffer, and neither the header arguments (including the value of
:var references) nor the text of the block itself has changed since
the result was last computed. This feature greatly helps avoid long-running
calculations. For some edge cases, however, the cached results may not be
The caching feature is best for when ‘src’ blocks are pure functions, that is functions that return the same value for the same input arguments (see var), and that do not have side effects, and do not rely on external variables other than the input arguments. Functions that depend on a timer, file system objects, and random number generators are clearly unsuitable for caching.
A note of warning: when
:cache is used for a
may cause unexpected results.
When the caching mechanism tests for any source code changes, it will not expand Noweb style references (see Noweb reference syntax). For reasons why, see http://thread.gmane.org/gmane.emacs.orgmode/79046.
:cache header argument can have one of two values:
noDefault. No caching of results; ‘src’ code block evaluated every time.
yesWhether to run the code or return the cached results is determined by comparing the SHA1 hash value of the combined ‘src’ code block and arguments passed to it. This hash value is packed on the
#+RESULTS:line from previous evaluation. When hash values match, Org does not evaluate the ‘src’ code block. When hash values mismatch, Org evaluates the ‘src’ code block, inserts the results, recalculates the hash value, and updates
In this example, both functions are cached. But
caller runs only if
the result from
random has changed since the last run.
#+NAME: random #+BEGIN_SRC R :cache yes runif(1) #+END_SRC #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random 0.4659510825295 #+NAME: caller #+BEGIN_SRC emacs-lisp :var x=random :cache yes x #+END_SRC #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller 0.254227238707244