Header arguments and result types in Org Babel

Table of Contents

For a complete header argument reference see the Org-mode manual's page which lists all Specific-header-arguments. This page holds ancillary notes and tricks which have not made it into the manual.

Generally use verbatim when using drawer, raw or org

We often want to add verbatim (which inhibits interpretation as a value, which can often result in a list or table result), when inserting results directly into the buffer using drawer, raw or org which don't do tabular interpretation.

An example w/o verbatim.

#+begin_src sh :results drawer
cat <<EOF
| 1 | 2
|--
| a | b
EOF
#+end_src

#+RESULTS:
:RESULTS:
|   |    | 1 |   |   | 2 |
|   | -- |   |   |   |   |
|   |    | a |   |   | b |
:END:

The same block with the verbatim flag.

#+begin_src sh :results verbatim drawer
cat <<EOF
| 1 | 2
|--
| a | b
EOF
#+end_src

#+RESULTS:
:RESULTS:
| 1 | 2 |
|---+---|
| a | b |
:END:

Common combinations of header-args and result types

Many combinations of header arguments and result types are supported by Org Babel. Individual languages may even define special header args. Like always in combinatorics, the number of possible combinations increases rapidly when there are several factors with several levels each that can be freely combined.

The following table shows combinations of header arguments and result types that might be considered reasonable for many programming languages.

evaluation collection type
(:session) (:results) (:results)
external value table (vector)
    scalar (verbatim)
    file
    raw (org)
    html
    latex
    code
    pp
  output table (vector)
    scalar (verbatim)
    file
    raw (org)
    html
    latex
    code
    pp
session value table (vector)
    scalar (verbatim)
    file
    raw (org)
    html
    latex
    code
    pp
  output table (vector)
    scalar (verbatim)
    file
    raw (org)
    html
    latex
    code
    pp

More special header arguments and their possible values are summarized in the next table:

header-arg   values    
:results silent replace append prepend
(handling)        
:exports code results both none
:comments yes (no?)    
:noweb no yes    
:tangle yes no filename  
:no-expand        
:file        
:dir        
:cache no yes    
:var x=y      
:hlines no yes    
:colnames nil no yes  
:rownames no yes    
:shebang "string"      
:eval never query    

Setting language and file specific default header argument values

This may be useful to e.g., have all Python code blocks in a file use the same session. The following file-local-variable syntax should be used, placing the customization at the end of the Org-mode file.

#+Title: Example of default file and language session

The value in this buffer is...
#+begin_src emacs-lisp
  org-babel-default-header-args:Python
#+end_src

#+RESULTS:
| (:session . foo) |

# Local Variables:
# eval: (setq-local org-babel-default-header-args:Python '((:session . "foo")))
# End:

Documentation from the orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.