15.3 Using Header Arguments

Org comes with many header arguments common to all languages. New header arguments are added for specific languages as they become available for use in source code blocks. A header argument is specified with an initial colon followed by the argument’s name in lowercase.

Since header arguments can be set in several ways, Org prioritizes them in case of overlaps or conflicts by giving local settings a higher priority. Header values in function calls, for example, override header values from global defaults.

System-wide header arguments

System-wide values of header arguments can be specified by customizing the org-babel-default-header-args variable, which defaults to the following values:

:session    => "none"
:results    => "replace"
:exports    => "code"
:cache      => "no"
:noweb      => "no"

The example below sets ‘:noweb’ header arguments to ‘yes’, which makes Org expand ‘:noweb’ references by default.

(setq org-babel-default-header-args
      (cons '(:noweb . "yes")
            (assq-delete-all :noweb org-babel-default-header-args)))

Each language can have separate default header arguments by customizing the variable org-babel-default-header-args:<LANG>, where <LANG> is the name of the language. For details, see the language-specific online documentation at https://orgmode.org/worg/org-contrib/babel/.

Header arguments in Org mode properties

For header arguments applicable to the buffer, use ‘PROPERTY’ keyword anywhere in the Org file (see Property Syntax).

The following example makes all the R code blocks execute in the same session. Setting ‘:results’ to ‘silent’ ignores the results of executions for all blocks, not just R code blocks; no results inserted for any block.

#+PROPERTY: header-args:R  :session *R*
#+PROPERTY: header-args    :results silent

Header arguments set through Org’s property drawers (see Property Syntax) apply at the sub-tree level on down. Since these property drawers can appear anywhere in the file hierarchy, Org uses outermost call or source block to resolve the values. Org ignores org-use-property-inheritance setting.

In this example, ‘:cache’ defaults to ‘yes’ for all code blocks in the sub-tree.

* sample header
  :PROPERTIES:
  :header-args:    :cache yes
  :END:

Properties defined through org-set-property function, bound to C-c C-x p, apply to all active languages. They override properties set in org-babel-default-header-args.

Language-specific header arguments are also read from properties ‘header-args:<LANG>’ where <LANG> is the language identifier. For example,

* Heading
  :PROPERTIES:
  :header-args:clojure:    :session *clojure-1*
  :header-args:R:          :session *R*
  :END:
** Subheading
  :PROPERTIES:
  :header-args:clojure:    :session *clojure-2*
  :END:

would force separate sessions for Clojure blocks in ‘Heading’ and ‘Subheading’, but use the same session for all R blocks. Blocks in ‘Subheading’ inherit settings from ‘Heading’.

Code block specific header arguments

Header arguments are most commonly set at the source code block level, on the ‘#+BEGIN_SRC’ line. Arguments set at this level take precedence over those set in the org-babel-default-header-args variable, and also those set as header properties.

In the following example, setting ‘:results’ to ‘silent’ makes it ignore results of the code execution. Setting ‘:exports’ to ‘code’ exports only the body of the code block to HTML or LaTeX.

#+NAME: factorial
#+BEGIN_SRC haskell :results silent :exports code :var n=0
  fac 0 = 1
  fac n = n * fac (n-1)
#+END_SRC

The same header arguments in an inline code block:

src_haskell[:exports both]{fac 5}

Code block header arguments can span multiple lines using ‘#+HEADER:’ on each line. Note that Org currently accepts the plural spelling of ‘#+HEADER:’ only as a convenience for backward-compatibility. It may be removed at some point.

Multi-line header arguments on an unnamed code block:

#+HEADER: :var data1=1
#+BEGIN_SRC emacs-lisp :var data2=2
   (message "data1:%S, data2:%S" data1 data2)
#+END_SRC

#+RESULTS:
: data1:1, data2:2

Multi-line header arguments on a named code block:

#+NAME: named-block
#+HEADER: :var data=2
#+BEGIN_SRC emacs-lisp
  (message "data:%S" data)
#+END_SRC

#+RESULTS: named-block
  : data:2

Header arguments in function calls

Header arguments in function calls are the most specific and override all other settings in case of an overlap. They get the highest priority. Two ‘#+CALL:’ examples are shown below. For the complete syntax of ‘CALL’ keyword, see Evaluating Code Blocks.

In this example, ‘:exports results’ header argument is applied to the evaluation of the ‘#+CALL:’ line.

#+CALL: factorial(n=5) :exports results

In this example, ‘:session special’ header argument is applied to the evaluation of ‘factorial’ code block.

#+CALL: factorial[:session special](n=5)