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"
:hlines     => "no"
:tangle     => "no"

Inline source blocks (see Structure of Code Blocks) use slightly different default header arguments defined in org-babel-default-inline-header-args:

:session    => "none"
:results    => "replace"
:exports    => "results"
:hlines     => "yes"

The most notable difference between default header arguments for inline and normal source blocks is :exports argument. For inline source blocks, results of evaluation are exported by default; not the code.

Unlike the default values, header arguments set using Org mode properties (see Header arguments in Org mode properties) do apply to both the normal source blocks and inline source blocks.

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/.

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 subtree 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 subtree.

* 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.

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 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)

Use var for passing arguments to source code blocks. The specifics of variables in code blocks vary by the source language and are covered in the language-specific documentation. The syntax for var, however, is the same for all languages. This includes declaring a variable, and assigning a default value.

The following syntax is used to pass arguments to code blocks using the var header argument.

:var NAME=ASSIGN

NAME is the name of the variable bound in the code block body. ASSIGN is a literal value, such as a string, a number, a reference to a table, a list, a literal example, another code block—with or without arguments—or the results of evaluating a code block. ASSIGN may specify a filename for references to elements in a different file, using a : to separate the filename from the reference.

:var NAME=FILE:REFERENCE

When FILE does not exist, the reference is searched in the current file, using the verbatim reference. This way, :var table=tbl:example will be searched inside the current buffer.

Here are examples of passing values by reference:

table

A table named with a NAME keyword.

#+NAME: example-table
| 1 |
| 2 |
| 3 |
| 4 |

#+NAME: table-length
#+BEGIN_SRC emacs-lisp :var table=example-table
  (length table)
#+END_SRC

#+RESULTS: table-length
: 4

When passing a table, you can treat specially the row, or the column, containing labels for the columns, or the rows, in the table.

The colnames header argument accepts yes, no, or nil values. The default value is nil: if an input table has column names—because the second row is a horizontal rule—then Org removes the column names, processes the table, puts back the column names, and then writes the table to the results block. Using yes, Org does the same to the first non-hline row, even if the initial table does not contain any horizontal rule. When set to no, Org does not pre-process column names at all.

#+NAME: less-cols
| a |
|---|
| b |
| c |

#+BEGIN_SRC python :var tab=less-cols :colnames nil
return [[val + '*' for val in row] for row in tab]
#+END_SRC

#+RESULTS:
| a  |
|----|
| b* |
| c* |

Similarly, the rownames header argument can take two values: yes or no. When set to yes, Org removes the first column, processes the table, puts back the first column, and then writes the table to the results block. The default is no, which means Org does not pre-process the first column. Note that Emacs Lisp code blocks ignore rownames header argument because of the ease of table-handling in Emacs.

#+NAME: with-rownames
| one | 1 | 2 | 3 | 4 |  5 |
| two | 6 | 7 | 8 | 9 | 10 |

#+BEGIN_SRC python :var tab=with-rownames :rownames yes
return [[val + 10 for val in row] for row in tab]
#+END_SRC

#+RESULTS:
| one | 11 | 12 | 13 | 14 | 15 |
| two | 16 | 17 | 18 | 19 | 20 |

To refer to a table in another file, join the filename and table name with a colon, for example: :var table=other-file.org:example-table.

list

A simple named list.

#+NAME: example-list
- simple
  - not
  - nested
- list

#+BEGIN_SRC emacs-lisp :var x=example-list
  (print x)
#+END_SRC

#+RESULTS:
| simple | list |

Note that only the top level list items are passed along. Nested list items are ignored.

code block without arguments

A code block name, as assigned by NAME keyword from the example above, optionally followed by parentheses.

#+BEGIN_SRC emacs-lisp :var length=table-length()
  (* 2 length)
#+END_SRC

#+RESULTS:
: 8

code block with arguments

A code block name, as assigned by NAME keyword, followed by parentheses and optional arguments passed within the parentheses. The block is evaluated with point at its location.

#+NAME: double
#+BEGIN_SRC emacs-lisp :var input=8
  (* 2 input)
#+END_SRC

#+RESULTS: double
: 16

#+NAME: squared
#+BEGIN_SRC emacs-lisp :var input=double(input=1)
  (* input input)
#+END_SRC

#+RESULTS: squared
: 4

literal example, or code block contents

A code block or literal example block named with a NAME keyword, followed by brackets (optional for example blocks).

#+NAME: literal-example
#+BEGIN_EXAMPLE
  A literal example
  on two lines
#+END_EXAMPLE

#+NAME: read-literal-example
#+BEGIN_SRC emacs-lisp :var x=literal-example[]
  (concatenate #'string x " for you.")
#+END_SRC

#+RESULTS: read-literal-example
: A literal example
: on two lines for you.

Indexing variable values enables referencing portions of a variable. Indexes are 0 based with negative values counting backwards from the end. If an index is separated by commas then each subsequent section indexes as the next dimension. Note that this indexing occurs before other table-related header arguments are applied, such as hlines, colnames and rownames. The following example assigns the last cell of the first row the table example-table to the variable data:

#+NAME: example-table
| 1 | a |
| 2 | b |
| 3 | c |
| 4 | d |

#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
  data
#+END_SRC

#+RESULTS:
: a

Two integers separated by a colon reference a range of variable values. In that case the entire inclusive range is referenced. For example the following assigns the middle three rows of example-table to data.

#+NAME: example-table
| 1 | a |
| 2 | b |
| 3 | c |
| 4 | d |
| 5 | 3 |

#+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
  data
#+END_SRC

#+RESULTS:
| 2 | b |
| 3 | c |
| 4 | d |

To pick the entire range, use an empty index, or the single character *. 0:-1 does the same thing. Example below shows how to reference the first column only.

#+NAME: example-table
| 1 | a |
| 2 | b |
| 3 | c |
| 4 | d |

#+BEGIN_SRC emacs-lisp :var data=example-table[,0]
  data
#+END_SRC

#+RESULTS:
| 1 | 2 | 3 | 4 |

Index referencing can be used for tables and code blocks. Index referencing can handle any number of dimensions. Commas delimit multiple dimensions, as shown below.

#+NAME: 3D
#+BEGIN_SRC emacs-lisp
  '(((1  2  3)  (4  5  6)  (7  8  9))
    ((10 11 12) (13 14 15) (16 17 18))
    ((19 20 21) (22 23 24) (25 26 27)))
#+END_SRC

#+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
  data
#+END_SRC

#+RESULTS:
| 11 | 14 | 17 |

Note that row names and column names are not removed prior to variable indexing. You need to take them into account, even when colnames or rownames header arguments remove them.

Emacs lisp code can also set the values for variables. To differentiate a value from Lisp code, Org interprets any value starting with (, [, ' or ` as Emacs Lisp code. The result of evaluating that code is then assigned to the value of that variable. The following example shows how to reliably query and pass the file name of the Org mode buffer to a code block using headers. We need reliability here because the file's name could change once the code in the block starts executing.

#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
  wc -w $filename
#+END_SRC

Note that values read from tables and lists are not mistakenly evaluated as Emacs Lisp code, as illustrated in the following example.

#+NAME: table
| (a b c) |

#+HEADER: :var data=table[0,0]
#+BEGIN_SRC perl
  $data
#+END_SRC

#+RESULTS:
: (a b c)

Two code blocks can share the same environment. The session header argument is for running multiple source code blocks under one session. Org runs code blocks with the same session name in the same interpreter process.

none

Default. Each code block gets a new interpreter process to execute. The process terminates once the block is evaluated.

STRING

Any string besides none turns that string into the name of that session. For example, :session STRING names it STRING. If session has no value, then the session name is derived from the source language identifier. Subsequent blocks with the same source code language use the same session. Depending on the language, state variables, code from other blocks, and the overall interpreted environment may be shared. Some interpreted languages support concurrent sessions when subsequent source code language blocks change session names.

Only languages that provide interactive evaluation can have session support. Not all languages provide this support, such as C and ditaa. Even languages, such as Python and Haskell, that do support interactive evaluation impose limitations on allowable language constructs that can run interactively. Org inherits those limitations for those code blocks running in a session.

The dir header argument specifies the default directory during code block execution. If it is absent, then the directory associated with the current buffer is used. In other words, supplying :dir DIRECTORY temporarily has the same effect as changing the current directory with M-x cd RET DIRECTORY, and then not setting dir. Under the surface, dir simply sets the value of the Emacs variable default-directory. Setting mkdirp header argument to a non-nil value creates the directory, if necessary.

Setting dir to the symbol attach or the string "'attach" will set dir to the directory returned by (org-attach-dir), set :mkdirp yes, and insert any file paths, as when using :results file, which are under the node's attachment directory using attachment: links instead of the usual file: links. Any returned path outside the attachment directory will use file: links as per usual.

For example, to save the plot file in the Work/ folder of the home directory—notice tilde is expanded:

#+BEGIN_SRC R :file myplot.png :dir ~/Work
  matplot(matrix(rnorm(100), 10), type="l")
#+END_SRC

To evaluate the code block on a remote machine, supply a remote directory name using Tramp syntax. For example:

#+BEGIN_SRC R :file plot.png :dir /scp:dand@yakuba.princeton.edu:
  plot(1:10, main=system("hostname", intern=TRUE))
#+END_SRC

Org first captures the text results as usual for insertion in the Org file. Then Org also inserts a link to the remote file, thanks to Emacs Tramp. Org constructs the remote path to the file name from dir and default-directory, as illustrated here:

[[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]

When dir is used with session, Org sets the starting directory for a new session. But Org does not alter the directory of an already existing session.

Do not use dir with :exports results or with :exports both to avoid Org inserting incorrect links to remote files. That is because Org does not expand default directory to avoid some underlying portability issues.

The prologue header argument is for appending to the top of the code block for execution, like a reset instruction. For example, you may use :prologue "reset" in a Gnuplot code block or, for every such block:

(add-to-list 'org-babel-default-header-args:gnuplot
             '((:prologue . "reset")))

Likewise, the value of the epilogue header argument is for appending to the end of the code block for execution.

Org captures the results of the code block evaluation and inserts them in the Org file, right after the code block. The insertion point is after a newline and the RESULTS keyword. Org creates the RESULTS keyword if one is not already there. More details in Results of Evaluation.

By default, Org enables only Emacs Lisp code blocks for execution. See Languages to enable other languages.

Org provides many ways to execute code blocks. C-c C-c or C-c C-v e with the point on a code block(note: The option org-babel-no-eval-on-ctrl-c-ctrl-c can be used to remove code evaluation from the C-c C-c key binding.) calls the org-babel-execute-src-block function, which executes the code in the block, collects the results, and inserts them in the buffer.

By calling a named code block⁴⁹ from an Org mode buffer or a table. Org can call the named code blocks from the current Org mode buffer or from the "Library of Babel" (see Library of Babel).

The syntax for CALL keyword is:

#+CALL: <name>(<arguments>)
#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>

The syntax for inline named code blocks is:

... call_<name>(<arguments>) ...
... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...

When inline syntax is used, the result is wrapped based on the variable org-babel-inline-result-wrap, which by default is set to "=%s=" to produce verbatim text suitable for markup.

<name>

This is the name of the code block (see Structure of Code Blocks) to be evaluated in the current document. If the block is located in another file, start <name> with the file name followed by a colon. For example, in order to execute a block named clear-data in file.org, you can write the following:

#+CALL: file.org:clear-data()

<arguments>

Org passes arguments to the code block using standard function call syntax. For example, a #+CALL: line that passes 4 to a code block named double, which declares the header argument :var n=2, would be written as:

#+CALL: double(n=4)

Note how this function call syntax is different from the header argument syntax.

<inside header arguments>

Org passes inside header arguments to the named code block using the header argument syntax. Inside header arguments apply to code block evaluation. For example, [:results output] collects results printed to stdout during code execution of that block. Note how this header argument syntax is different from the function call syntax.

<end header arguments>

End header arguments affect the results returned by the code block. For example, :results html wraps the results in a #+BEGIN_EXPORT html block before inserting the results in the Org buffer.

The eval header argument can limit evaluation of specific code blocks and CALL keyword. It is useful for protection against evaluating untrusted code blocks by prompting for a confirmation.

yes

Org evaluates the source code, possibly asking permission according to org-confirm-babel-evaluate.

never or no

Org never evaluates the source code.

query

Org prompts the user for permission to evaluate the source code.

never-export or no-export

Org does not evaluate the source code when exporting, yet the user can evaluate it interactively.

query-export

Org prompts the user for permission to evaluate the source code during export.

If eval header argument is not set, then Org determines whether to evaluate the source code from the org-confirm-babel-evaluate variable (see Code Evaluation and Security Issues).

The cache header argument is for caching results of evaluating code blocks. Caching results can avoid re-evaluating a code block 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 reliable.

The caching feature is best for when code blocks are pure functions, that is functions that return the same value for the same input arguments (see Environment of a Code Block), 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 in a session, caching may cause unexpected results.

When the caching mechanism tests for any source code changes, it does not expand noweb style references (see Noweb Reference Syntax).

The cache header argument can have one of two values: yes or no.

no

Default. No caching of results; code block evaluated every time.

yes

Whether to run the code or return the cached results is determined by comparing the SHA1 hash value of the combined 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 code block. When hash values mismatch, Org evaluates the code block, inserts the results, recalculates the hash value, and updates #+RESULTS: line.

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

Collection options specify the results. Choose one of the options; they are mutually exclusive.

value

Default for most Babel libraries⁴⁹. Functional mode. Org gets the value by wrapping the code in a function definition in the language of the source block. That is why when using :results value, code should execute like a function and return a value. For languages like Python, an explicit return statement is mandatory when using :results value. Result is the value returned by the last statement in the code block.

When evaluating the code block in a session (see Environment of a Code Block), Org passes the code to an interpreter running as an interactive Emacs inferior process. Org gets the value from the source code interpreter's last statement output. Org has to use language-specific methods to obtain the value. For example, from the variable _ in Ruby, and the value of .Last.value in R.

output

Scripting mode. Org passes the code to an external process running the interpreter. Org returns the contents of the standard output stream as text results. When using a session, Org passes the code to the interpreter running as an interactive Emacs inferior process. Org concatenates any text output from the interpreter and returns the collection as a result.

Type tells what result types to expect from the execution of the code block. Choose one of the options; they are mutually exclusive.

The default behavior is to automatically determine the result type. The result type detection depends on the code block language, as described in the documentation for individual languages. See Languages.

table, vector

Interpret the results as an Org table. If the result is a single value, create a table with one row and one column. Usage example: :results value table.

In-between each table row or below the table headings, sometimes results have horizontal lines, which are also known as "hlines". The hlines argument with the default no value strips such lines from the input table. For most code, this is desirable, or else those hline symbols raise unbound variable errors. A yes accepts such lines, as demonstrated in the following example.

#+NAME: many-cols
| a | b | c |
|---+---+---|
| d | e | f |
|---+---+---|
| g | h | i |

#+NAME: no-hline
#+BEGIN_SRC python :var tab=many-cols :hlines no
return tab
#+END_SRC

#+RESULTS: no-hline
| a | b | c |
| d | e | f |
| g | h | i |

#+NAME: hlines
#+BEGIN_SRC python :var tab=many-cols :hlines yes
return tab
#+END_SRC

#+RESULTS: hlines
| a | b | c |
|---+---+---|
| d | e | f |
|---+---+---|
| g | h | i |

list

Interpret the results as an Org list. If the result is a single value, create a list of one element.

scalar, verbatim

Interpret literally and insert as quoted text. Do not create a table. Usage example: :results value verbatim.

file

Interpret as a filename. Save the results of execution of the code block to that file, then insert a link to it. You can control both the filename and the description associated to the link.

Org first tries to generate the filename from the value of the file header argument and the directory specified using the output-dir header arguments. If output-dir is not specified, Org assumes it is the current directory.

#+BEGIN_SRC asymptote :results value file :file circle.pdf :output-dir img/
  size(2cm);
  draw(unitcircle);
#+END_SRC

If file header argument is missing, Org generates the base name of the output file from the name of the code block, and its extension from the file-ext header argument. In that case, both the name and the extension are mandatory.

Result can also be interpreted as path to file. See :results link.

#+name: circle
#+BEGIN_SRC asymptote :results value file :file-ext pdf
  size(2cm);
  draw(unitcircle);
#+END_SRC

The file-desc header argument defines the description (see Link Format) for the link. If file-desc is present but has no value, the file value is used as the link description. When this argument is not present, the description is omitted. If you want to provide the file-desc argument but omit the description, you can provide it with an empty vector (i.e., :file-desc []).

By default, Org assumes that a table written to a file has TAB-delimited output. You can choose a different separator with the sep header argument.

The file-mode header argument defines the file permissions. To make it executable, use :file-mode (identity #o755).

#+BEGIN_SRC shell :results file :file script.sh :file-mode (identity #o755)
  echo "#!/bin/bash"
  echo "echo Hello World"
#+END_SRC

Format pertains to the type of the result returned by the code block. Choose one of the options; they are mutually exclusive. The default follows from the type specified above.

raw

Interpreted as raw Org mode. Inserted directly into the buffer. Aligned if it is a table. Usage example: :results value raw.

code

Result enclosed in a code block. Useful for parsing. Usage example: :results value code.

drawer

Results are added directly to the Org file as with raw, but are wrapped in a RESULTS drawer or results macro (for inline code blocks), for later scripting and automated processing. Usage example: :results value drawer.

html

Results enclosed in a BEGIN_EXPORT html block. Usage example: :results value html.

latex

Results enclosed in a BEGIN_EXPORT latex block. Usage example: :results value latex.

link, graphics

When used along with file type, the result is a link to the file specified in :file header argument. However, unlike plain file type, code block output is not written to the disk. The block is expected to generate the file by its side effects only, as in the following example:

#+begin_src shell :results file link :file "org-mode-unicorn.svg"
  wget -c "https://orgmode.org/resources/img/org-mode-unicorn.svg"
#+end_src

#+RESULTS:
[[file:org-mode-unicorn.svg]]

If :file header argument is omitted, interpret source block result as the file path.

org

Results enclosed in a BEGIN_SRC org block. For comma-escape, either TAB in the block, or export the file. Usage example: :results value org.

pp

Result converted to pretty-print source code. Enclosed in a code block. Languages supported: Emacs Lisp, Python, and Ruby. Usage example: :results value pp.

The wrap header argument unconditionally marks the results block by appending strings to #+BEGIN_ and #+END_, except if the value is nil or no. If no string is specified, Org wraps the results in a #+BEGIN_results … #+END_results block. It takes precedent over the results value listed above. E.g.,

#+BEGIN_SRC emacs-lisp :results html :wrap EXPORT markdown
"<blink>Welcome back to the 90's</blink>"
#+END_SRC

#+RESULTS:
#+BEGIN_EXPORT markdown
<blink>Welcome back to the 90's</blink>
#+END_EXPORT

Handling options after collecting the results. Choose one of the options; they are mutually exclusive.

replace

Default. Insert results in the Org buffer. Remove previous results. Usage example: :results output replace.

silent

Do not insert results in the Org mode buffer, but echo them in the minibuffer. Usage example: :results output silent.

none

Compute results, but do not do anything with them. No inserting in the Org mode buffer nor echo them in the minibuffer. The results can still be used when referenced from another code block. Usage example: :results none.

discard

Ignore the results completely. This option is similar to none, but no processing is performed on the return value. Calling the code block programmatically (see How to evaluate source code) or by reference (see Passing arguments and Noweb Reference Syntax) will always yield nil.

append

Append results to the Org buffer. Latest results are at the bottom. Does not remove previous results. Usage example: :results output append.

prepend

Prepend results to the Org buffer. Latest results are at the top. Does not remove previous results. Usage example: :results output prepend.

The post header argument is for post-processing results from block evaluation. When post has any value, Org binds the results to *this* variable for easy passing to var header argument specifications (see Environment of a Code Block). That makes results available to other code blocks, or even for direct Emacs Lisp code execution.

The following two examples illustrate post header argument in action. The first one shows how to attach an ATTR_LATEX keyword using post.

#+NAME: attr_wrap
#+BEGIN_SRC sh :var data="" :var width="\\textwidth" :results output
  echo "#+ATTR_LATEX: :width $width"
  echo "$data"
#+END_SRC

#+HEADER: :file /tmp/it.png
#+BEGIN_SRC dot :post attr_wrap(width="5cm", data=*this*) :results drawer
  digraph{
          a -> b;
          b -> c;
          c -> a;
  }
#+end_src

#+RESULTS:
:RESULTS:
#+ATTR_LATEX :width 5cm
[[file:/tmp/it.png]]
:END:

The second example shows use of colnames header argument in post to pass data between code blocks.

#+NAME: round-tbl
#+BEGIN_SRC emacs-lisp :var tbl="" fmt="%.3f"
  (mapcar (lambda (row)
            (mapcar (lambda (cell)
                      (if (numberp cell)
                          (format fmt cell)
                        cell))
                    row))
          tbl)
#+end_src

#+BEGIN_SRC R :colnames yes :post round-tbl[:colnames yes](*this*)
  set.seed(42)
  data.frame(foo=rnorm(1))
#+END_SRC

#+RESULTS:
|   foo |
|-------|
| 1.371 |

The tangle header argument specifies if the code block is exported to source file(s).

yes

Export the code block to source file. The file name for the source file is derived from the name of the Org file, and the file extension is derived from the source code language identifier. Example: :tangle yes.

no

The default. Do not extract the code in a source code file. Example: :tangle no.

FILENAME

Export the code block to source file whose file name is derived from any string passed to the tangle header argument. Org derives the file name as being relative to the directory of the Org file's location. Example: :tangle FILENAME.

Additionally, code blocks inside commented subtrees (see Comment Lines) are never exported.

The mkdirp header argument creates parent directories for tangled files if the directory does not exist. A yes value enables directory creation whereas no inhibits it.

The comments header argument controls inserting comments into tangled files. These are above and beyond whatever comments may already exist in the code block.

no

The default. Do not insert any extra comments during tangling.

link

Wrap the code block in comments. Include links pointing back to the place in the Org file from where the code was tangled.

Do note that Org will use org-store-link (Handling Links) to store link to code block. Such link may not be unique if the parent heading title is a duplicate of earlier heading or changes after tangling. We recommend setting org-id-link-to-org-use-id to t to make sure that the link points to the correct heading.

yes

Kept for backward compatibility; same as link.

org

Nearest headline text from Org file is inserted as comment. The exact text that is inserted is picked from the leading context of the source block.

both

Includes both link and org options.

noweb

Includes link option, expands noweb references (see Noweb Reference Syntax), and wraps them in link comments inside the body of the code block.

The padline header argument controls insertion of newlines to pad source code in the tangled file.

yes

Default. Insert a newline before and after each code block in the tangled file.

no

Do not insert newlines to pad the tangled code blocks.

The shebang header argument can turn results into executable script files. By setting it to a string value—for example, :shebang "#!/bin/bash"—Org inserts that string as the first line of the tangled file that the code block is extracted to. Org then turns on the tangled file's executable permission.

The tangle-mode header argument specifies what permissions to set for tangled files by set-file-modes. Permissions are given by an octal value, which can be provided calling the identity function on an elisp octal value. For instance, to create a read-only file one may use :tangle-mode (identity #o444). To reduce the verbosity required, a octal shorthand is defined, oXXX (o for octal). Using this, our read-only example is :tangle-mode o444. Omitting the o prefix will cause the argument to be interpreted as an integer, which can lead to unexpected results (444 is the same as o674). Two other shorthands are recognized, ls-style strings like rw-r--r--, and chmod-style permissions like g+w. Note that chmod-style permissions are based on org-babel-tangle-default-file-mode, which is #o644 by default.

When :tangle-mode and :shebang are both specified, the give :tangle-mode will override the permissions from :shebang. When multiple source code blocks tangle to a single file with conflicting :tangle-mode header arguments, Org's behavior is undefined.

By default Org expands code blocks during tangling. The no-expand header argument turns off such expansions. Note that one side effect of expansion by org-babel-expand-src-block also assigns values (see Environment of a Code Block) to variables. Expansions also replace noweb references with their targets (see Noweb Reference Syntax). Some of these expansions may cause premature assignment, hence this option. This option makes a difference only for tangling. It has no effect when exporting since code blocks for execution have to be expanded anyway.

org-babel-tangle

Tangle the current file. Bound to C-c C-v t.

With prefix argument only tangle the current code block.

org-babel-tangle-file

Choose a file to tangle. Bound to C-c C-v f.

org-babel-pre-tangle-hook

This hook is run before the tangle process begins. The active buffer is buffer to be tangled.

org-babel-tangle-body-hook

This hook is run from a temporary buffer containing expanded code of every tangled code block. The hook can modify the expanded code as needed. The contents of the current buffer will be used as actual code block expansion.

org-babel-post-tangle-hook

This hook is run from within code files tangled by org-babel-tangle, making it suitable for post-processing, compilation, and evaluation of code in the tangled files.

org-babel-tangle-finished-hook

This hook is run after post-tangle hooks, in the original buffer.

Debuggers normally link errors and messages back to the source code. But for tangled files, we want to link back to the Org file, not to the tangled source file. To make this extra jump, Org uses org-babel-tangle-jump-to-org function with two additional source code block header arguments:

1. Set padline to true—this is the default setting.
2. Set comments to link, which makes Org insert links to the Org file.