Source blocks (Babel) in depth

Lua blocks run inside Neovim: they always work, need nothing installed, and can use the whole vim API. sh needs a POSIX shell, which every Unix-like system has. All the exercises use one of these two. A few examples show other languages; they only run when the interpreter is on your $PATH:

:checkhealth org reports which of them it found.

By default you are asked before every evaluation (Emacs org-confirm-babel-evaluate). This is the option babel.confirm_evaluate:

require("org").setup({
  babel = {
    -- never ask:
    confirm_evaluate = false,
    -- or: ask for everything except Lua
    -- confirm_evaluate = function(lang, body) return lang ~= "lua" end,
  },
})

Try: to stop the prompts for this session only, run this command: :lua require("org.config").opts.babel.confirm_evaluate = false

Expect: <C-c><C-c> on a block runs it at once, without a question. Restart Neovim to get the prompt back.

The :eval header argument controls one block:

return "you will never see me"

Try: press <C-c><C-c> in the :eval no block above.

Expect: nothing is inserted; a message says evaluation is disabled.

• <prefix>bk in a block deletes its result. With a count (1<prefix>bk, Emacs C-u C-c C-v k) it deletes every result in the buffer.
• <Tab> on a #+RESULTS: line folds the result; :Org babel_hide_all_results folds all of them.

return { "alpha", "beta", "gamma", "delta" }

Try: put the cursor in the block above and press <prefix>bk.

Expect: the #+RESULTS: line and the four-column table under it are gone. Press <C-c><C-c> to bring them back, then <Tab> on the #+RESULTS: line to fold and unfold them.

• <prefix>bb runs every block (and #+CALL: line and inline block) of the buffer, from top to bottom.
• <prefix>bs runs every block of the current subtree.

Each one is confirmed unless prompts are off. Blocks with :eval no are skipped. Don't use <prefix>bb on this whole file before the "Library of Babel" exercise: its #+CALL: lines stop the run with an error until the library is loaded, and the session blocks start shells.

Try: on the "Running a block" heading press <prefix>bs.

Expect: every block of this section runs once (answer y each time); the :eval no blocks are skipped and keep having no result.

Try: on this line press <prefix>bp twice, then <prefix>bn.

Expect: the cursor jumps from #+begin_src line to #+begin_src line. <prefix>bg then square jumps to the square block in "Named blocks".

Lua needs nothing installed. A block that is a single expression returns its value; otherwise use return. print goes to the output (see "Results").

local words = vim.split("the quick brown fox", " ")
return #words .. " words, longest: " .. vim.iter(words):fold("", function(a, w)
  return #w > #a and w or a
end)

4 words, longest: quick

Several return values are joined with , =; =nil gives nil:

return "a", 2, true

a, 2, true

return nil

nil

A Lua table that is a list becomes an Org list-table (one row); a list of lists becomes a table; a table with keys becomes a two-column table sorted by key:

return { { "x", "x²" }, { 1, 1 }, { 2, 4 }, { 3, 9 } }

return { lang = "lua", version = 5.1, jit = jit ~= nil }

Try: in the key/value block above add , os = jit.os before the closing brace and press <C-c><C-c>.

Expect: a fourth row appears, sorted between lang and version, with your OS name (OSX, Linux or Windows).

Because the code runs in the editor, a block can act on the editor. This one counts the headings of this very file:

local n = 0
for _, l in ipairs(vim.api.nvim_buf_get_lines(0, 0, -1, false)) do
  if l:match("^%*+ ") then n = n + 1 end
end
return n .. " headings in this file"

50 headings in this file

(os.exit() or an endless loop would affect Neovim itself, and babel.timeout cannot stop Lua code.)

Shell blocks run sh (or bash, zsh, fish). By default their output is the result, and it is read like data: one line stays text, several lines become a table split at tabs, commas or runs of spaces.

echo "hello from sh"

hello from sh

printf 'apples 3\nbananas 12\ncherries 7\n'

Add :results output to keep the text as it is (see "Results"):

printf 'apples 3\nbananas 12\ncherries 7\n'

apples 3
bananas 12
cherries 7

Try: in the block above, change :results output to :results value and run it.

Expect: the result becomes : 0: for shells, the "value" is the exit status. Put back output.

Errors: what a program writes to stderr (and a non-zero exit code) goes to the *Org-Babel Error Output* buffer in a split; the result keeps only the standard output.

echo "this goes to the result"
echo "this goes to the error buffer" >&2
exit 3

Try: run the block above.

Expect: : this goes to the result under #+RESULTS:, and a split named *Org-Babel Error Output* that shows the stderr line and the exit code 3.

These show the same idea in other languages. They only run when the interpreter is installed; the results here were produced by org.nvim.

return [[n, n**2] for n in range(1, 4)]

console.log(["a", "b", "c"].map((s) => s.toUpperCase()).join("-"))

A-B-C

[1, 2, 3].sum * 10

60

select 'Mon' as day, 3 as tasks union all select 'Tue', 5;

BEGIN { for (i = 1; i <= 3; i++) printf "%d%s", i * i, (i < 3 ? " " : "\n") }

1 4 9

Emacs-lisp blocks run in a separate emacs --batch (not in the editor), and fall back to the formula interpreter of tables when Emacs is missing.

value is what the code returns, output what it prints.

print("printed")
return "returned"

returned

print("printed")
return "returned"

printed

A list-like value becomes a table unless you ask otherwise.

return { "red", "green", "blue" }

return { "red", "green", "blue" }

• red
• green
• blue

printf 'a b\nc d\n'

a b
c d

echo "one two three"

return { 1, 2, 3 }

(1 2 3)

Long text (babel.min_lines_for_block_output, 10 lines by default) goes into an example block instead of =: = lines:

for i = 1, 12 do print("line " .. i) end

line 1
line 2
line 3
line 4
line 5
line 6
line 7
line 8
line 9
line 10
line 11
line 12

By default text is quoted with =: =. Other formats insert it differently:

return "This is *bold* and /italic/."

This is bold and italic.

return "- item one\n- item two"

• item one
• item two

return "| a | b |\n| 1 | 2 |"

| a | b |
| 1 | 2 |

return "<b>bold</b>"

return "print('generated code')"

print('generated code')

Try: run the raw block above twice.

Expect: the text appears twice: a raw result has no end marker, so it cannot be found and replaced. That is what drawer is for: run the drawer block twice and it stays single.

:wrap wraps the result in any block: :wrap alone uses #+begin_results, :wrap src json a JSON src block, :wrap example an example block, :wrap export html an export block. Avoid :wrap quote or :wrap center: like in Emacs, those blocks are not recognised as a result, so every run adds another one instead of replacing it.

return vim.json.encode({ answer = 42 })

{"answer":42}

echo "an example block"

an example block

return "Wrapped in a results block."

• replace (the default) replaces the old result.
• append / prepend add the new result after / before the old one.
• silent shows the value as a message and writes nothing.
• none neither shows nor writes (useful for side effects).

return os.date("%H:%M:%S")

15:07:56

Try: press <C-c><C-c> three times in the block above, a few seconds apart.

Expect: three more times appear under #+RESULTS:, each below the previous one. Change append to prepend and the newest goes on top.

return "shown in the message area only"

Try: run the silent block.

Expect: the message "shown in the message area only" (quoted, like Emacs' %S) and no #+RESULTS: line.

With :cache yes the result is stored with a hash of the body and header arguments: #+RESULTS[hash]:. Running the block again does nothing while the hash matches. Change the body and it runs again.

return "computed at " .. os.date("%Y-%m-%d")

computed at 2026-09-28

Try: press <C-c><C-c> in the block above.

Expect: nothing changes in the buffer: the hash still matches and the cached value is reused. <prefix>ba shows the same hash as in #+RESULTS[...]:. Now add a space at the end of the return line and run it again: the hash changes and the date is today's. A count forces a run: 1<prefix>be (Emacs C-u C-c C-c).

With :results file and :file NAME the result is written to a file and a link to it is inserted. :output-dir says where (and is created). <prefix>bo opens the file.

echo "Written by babel on a Monday"

Try: run the block above, then press <prefix>bo in it.

Expect: #+RESULTS: followed by [[file:17-babel-out/hello.txt]], and <prefix>bo opens that file with the text "Written by babel on a Monday".

Numbers stay numbers, quoted text is a string. Several :var can be given on one line or in separate :var arguments.

return x * y

42

return greeting .. ", " .. name .. "!"

Hello, Ada!

In a shell, variables are shell variables:

i=0
while [ "$i" -lt "$n" ]; do echo "hello $who"; i=$((i + 1)); done

Try: change n=3 to n=5 in the #+begin_src line above and run it.

Expect: five hello world rows.

A value that looks like an Emacs Lisp list is a list; a form like (+ 1 2) is evaluated:

return "#xs = " .. #xs .. ", total = " .. total

#xs = 3, total = 6

A #+NAME: makes a table (or a list) available by name. A table arrives as a list of rows. The header row above the first hline is removed from the data by default.

local total = 0
for _, r in ipairs(rows) do total = total + r[2] * r[3] end
return string.format("%d rows, total %.2f", #rows, total)

3 rows, total 12.50

A named plain list arrives as a list of strings:

• milk
• eggs
• bread

return table.concat(items, " + ")

milk + eggs + bread

Try: add a line - butter to the shopping list and run the block again.

Expect: : milk + eggs + bread + butter.

In a shell, a one-column value is a string with one item per line, a table is lines of tab-separated cells:

echo "$items" | sort

bread
eggs
milk

name[i] picks row i, name[i,j] one cell, name[i:j] a range of rows (both ends included), name[,j] a column and name[i:j,k:l] a rectangle. Indexes are 0-based; negative ones count from the end.

These examples use a table without a header, so row 0 is the first line:

return r

return c

13

return col

return rows

return box

return last

Try: change grid[-1] to grid[0:1] and run it.

Expect: a two-row table: | 11 | 12 | 13 | and | 21 | 22 | 23 |.

In a table with a header, like fruit, the header row is row 0 and the hline is row 1 (as in Emacs), so the first data row is row 2:

return first

return names

return p

0.05

• :colnames yes takes the first row as column names and puts them back on a table result of the same width. :colnames no keeps the header as a data row.
• :rownames yes does the same for the first column.
• :hlines yes keeps the hlines of the input (in Lua they are the string "hline").

for _, r in ipairs(t) do r[3] = r[3] * 2 end
return t

return t

return #t .. " rows, first cell: " .. t[1][1]

4 rows, first cell: name

for _, r in ipairs(t) do r[1] = r[1] * 10 end
return t

return t

A :var that names a block runs that block and uses its result. The block does not need a #+RESULTS:; arguments can be passed like a call.

return n * n

4

return a + b

29

A block can produce a table that another block consumes:

local t = {}
for i = 1, 4 do t[#t + 1] = { i, i * i, i * i * i } end
return t

local s = 0
for _, v in ipairs(cubes) do s = s + v end
return s

100

name[] gives the body text of a block instead of its result:

return vim.trim(code)

return n * n

Try: change the body of square to return n * n * n and run the a + b block again (without running square).

Expect: : 133 (8 + 125): the referenced block is always evaluated.

Inside a paragraph, a small block is written src_ followed by the language and the code in braces, and a call is written call_ followed by the block name and its arguments in parentheses. Header arguments go in square brackets after the language. <C-c><C-c> on one of them inserts the result right after it, wrapped in a {{{results(...)}}} macro (which exports as the bare value).

Two times three is return 2 * 3 and the square of nine is . Header arguments go in brackets: echo "hi from sh" .

Try: in the paragraph above, delete the first {{{results(...)}}} (the one with the 6), put the cursor on the inline lua block before it and press <C-c><C-c>.

Expect: the same {{{results(...)}}} with 6 comes back. Running it again replaces it rather than adding a second one.

Raw: return 6 * 7

Try: press <C-c><C-c> on the raw block in the line above.

Expect: the line reads Raw: then the block, then a space and a bare 42. A table or list result cannot be inlined: changing the code to return {1, 2} gives the message "Inline error: list result cannot be used".

With parentheses, the reference is replaced by the result of running the block, not its body:

return "square(7) = <<square(n=7)>>"

square(7) = 49

Several blocks can share a :noweb-ref instead of a name; a reference then inserts all of them, joined with a newline (:noweb-sep changes it).

echo "step 1: fetch"

echo "step 2: build"

<<steps>>
echo "done"

step 1: fetch
step 2: build
done

Try: copy one of the two :noweb-ref steps blocks, change its text to "step 3: test" and run the last block.

Expect: four lines of output: step 1, step 2, step 3, done.

echo "before"
<<two-lines>>

Try: run the :noweb tangle block above.

Expect: the result is : before, and the *Org-Babel Error Output* split shows a syntax error about <<two-lines>> (it is not valid shell) and "exited with code 2". Change tangle to yes and it prints before, one and two.

A Lua session keeps its globals inside Neovim (nothing to install):

counter = (counter or 0) + 1
return "counter is " .. counter

counter is 1

return "the other block sees counter = " .. counter

the other block sees counter = 1

Try: run the first block three times, then the second one.

Expect: the first block shows counter is 1, then 2, then 3 (each Neovim starts with a fresh session). The second block then shows the other block sees counter = 3: they share counter. Without :session the second block would fail (counter would be nil).

A shell session keeps the working directory, variables and functions. It runs in a terminal buffer named *name* (*shell* for the default session).

cd /tmp
greeting="set in the first block"

pwd
echo "$greeting"

Try: run the two blocks above in order.

Expect: the first one gets an empty #+RESULTS: (it prints nothing); the second one prints /tmp and set in the first block. Without the session it would print the directory of this file and an empty line.

Try: in the second block press <prefix>bz.

Expect: a split with the *work* terminal buffer. Enter Insert mode, type echo $greeting and <CR>: the REPL answers "set in the first block". Define x=5 there; a block with :session work running echo $x now prints 5.

Other session keys:

• <prefix>bZ shows the session and also opens the edit buffer.
• <prefix>bl sends the block to its session and shows the session.
• <prefix>bK kills the session (the next run starts a fresh one).

Every evaluation already runs in the background, so Neovim never freezes. With :async yes (or just :async) on a session block, a placeholder id is written into #+RESULTS: at once and replaced by the result when it arrives, even if you keep editing in between (Lua sessions finish at once and ignore it).

sleep 3
echo "finished after 3 seconds"

Try: run the block above and keep typing elsewhere in the file.

Expect: first a #+RESULTS: line with a long random id under it, then after three seconds that id becomes : finished after 3 seconds.

Every Lua block below this heading gets base and :results verbatim. The heading's header-args:lua replaces the file's #+PROPERTY: header-args:lua :exports both (the nearest one wins), so <prefix>bI here shows :exports code. Writing the property as :header-args:lua+: would add to the inherited value instead.

return base + 1

101

return base + 1

6

return base + extra

1100

Try: change :var base=100 in the :PROPERTIES: drawer to :var base=200 and run the first block of this subtree.

Expect: : 201.

• <prefix>bj inserts a header argument on the #+begin_src line, with completion of names and values.
• <prefix>bc reports a header argument that looks like a misspelt one.

print("typo")

Try: press <prefix>bc in the block above.

Expect: the error Supplied header "resluts" is suspiciously close to "results". Fix the typo and press it again: "No suspicious header arguments found."

Try: in the same block press <prefix>bj, pick results, then silent.

Expect: = :results silent= is appended to the #+begin_src line.

• :dir PATH runs the block in that directory (:mkdirp yes creates it).
• :prologue / :epilogue add code before / after the body.
• :cmdline passes arguments to the interpreter.

pwd

/tmp

echo middle

start
middle
end

echo "$# arguments: $1 and $2"

2 arguments: alpha and beta

<prefix>' (Emacs C-c ') opens the body of the block in a separate buffer whose filetype matches the language, so you get that language's indentation, completion and LSP. Save with :w, or press <prefix>' / <C-c>' again to save and close.

local function add(a, b)
return a + b
end
return add(20, 22)

42

Try: in the block above press <prefix>', then gg=G to reindent, then <prefix>'.

Expect: you are back in this file. The body is now indented by two spaces (edit_src_content_indentation, 2 like Emacs) and the return a + b line one level more than the other lines. The same key edits example blocks, =: = fixed-width lines, LaTeX fragments and footnote definitions.

<prefix>bx does the same without opening a window: it asks for Normal mode keys, runs them in the edit buffer and writes the result back (gg=G reindents the block in one go).

<prefix>bd (org-babel-demarcate-block):

• inside a block: split it in two at the cursor line,
• on a Visual selection outside blocks: wrap the lines in a new block,
• elsewhere: insert an empty block (it asks for the language).

print("first half")
print("second half")

Try: put the cursor on print("second half") and press <prefix>bd.

Expect: two blocks, both #+begin_src lua :results output, with one print each.

Try: select the next two lines with V and j, then press <prefix>bd. At the Lang: prompt (it proposes the language of the block above), type sh and press <CR>.

echo "wrap me" echo "me too"

Expect: the two lines are now inside #+begin_src sh … #+end_src.

<prefix>bv shows what would actually run: noweb references expanded, :var assignments, :prologue and :epilogue added.

<<two-lines>>

Try: press <prefix>bv in the block above.

Expect: a split with n=3, set -e, echo one and echo two.

echo "Hello from a tangled script"

echo "Second block, same file"

Try: press <prefix>bt, then in a shell run sh examples/17-babel-out/hello.sh (or :!sh %:h/17-babel-out/hello.sh).

Expect: the message says the files were tangled; the script prints both lines. :e examples/17-babel-out/hello.sh shows #!/bin/sh on line 1, then the two echo lines separated by a blank line (:padline no removes it).

:comments link wraps each block in comments that link back here, so :Org tangle_jump in the tangled file jumps to the Org block and :Org detangle copies edits back. :comments org also writes the Org text before the block as comments.

local function double(x) return 2 * x end

local M = {}
<<mod-helpers>>
function M.quadruple(x) return double(double(x)) end
return M

Try: with the cursor in the block above press 1<prefix>bt (tangle only this block). Open examples/17-babel-out/mymod.lua.

Expect: the file starts with -- [[file:../17-babel.org::*A Lua module with link comments and noweb][A Lua module with link comments and noweb:2]] (:2 because it is the second block of that heading), has local function double where <<mod-helpers>> was, and ends with a -- A Lua module with link comments and noweb:2 ends here line. In that file, put the cursor inside the code and run :Org tangle_jump: you land back on this block.

Try: now load the module from a Lua block:

local path = vim.fn.expand("%:p:h") .. "/17-babel-out/mymod.lua"
if vim.fn.filereadable(path) == 0 then return "tangle it first" end
return dofile(path).quadruple(10)

Expect: : 40 once tangled, : tangle it first before.