Outlines · TODOs · Agenda · Capture · Clocking · Spreadsheet tables · Babel · Export
Install · Tour · Features · Docs · Guide · Try it in your browser · Changelog · Contributing
Org mode is one of the most loved tools in Emacs. It works as a plain-text outliner, planner, time tracker, spreadsheet, literate-programming notebook and publishing system. org.nvim puts all of that in Neovim. It isn't a syntax file with a few keymaps on top. It reimplements Org's behaviour: the agenda, capture templates, repeaters, clock tables, table formulas, Babel and export.
- 🪶 No dependencies. It's about 170k lines of Lua and needs no tree-sitter parser, external binary or companion plugin.
- 🔁 Works with Emacs. It reads and writes the same plain-text format, so you can edit a file in Emacs today and in Neovim tomorrow.
- ⌨️ Keys that fit Vim. Context-aware keys fall back to normal Vim
behaviour when they don't apply (
>>still indents,<C-a>still increments). Pressg?in an org or agenda buffer to see what's available. - 💤 Ready for LazyVim. It comes with which-key groups, a blink.cmp source, pickers for snacks.nvim, fzf-lua, Telescope and mini.pick, and a lualine clock, and it works with any other setup too.
- ✅ Tested. The headless test suite runs 4,800+ tests from 240+ spec files.
How does it compare with nvim-orgmode and Neorg? See why another Org plugin?.
Switching from nvim-orgmode? :h org-migrate maps its
options and keys to org.nvim's, and :Org migrate_config converts your setup.
On AI: org.nvim is written with AI assistance (Claude Code). To keep that honest, its behaviour is checked against the Emacs Org source rather than guessed, every feature comes with headless tests, and I review and use every change myself. Bug reports are very welcome, especially where it doesn't match Emacs.
With lazy.nvim / LazyVim:
-- ~/.config/nvim/lua/plugins/org.lua
return {
"xheisenbugx/org.nvim",
main = "org",
lazy = false, -- startup cost is small: heavy modules load on first use
opts = {
org_directory = "~/org",
agenda_files = { "~/org/**/*.org" },
default_notes_file = "~/org/refile.org",
},
}Not using lazy.nvim? The guide covers
vim.pack, plain Vim packages, a local checkout and blink.cmp completion.
Neovim 0.11+ on Linux, macOS or Windows is all it needs; pandoc, LaTeX
and Babel's interpreters are optional (requirements).
Restart Neovim and run :checkhealth org. New to Org? Run :Org tutor:
it lists the lessons of a guided course, like vimtutor, each in a copy
of its own where every org key works and each exercise gets a ✓ once you
have done it (:Org tutor basics starts with the first; :h org-tutor).
Not installed yet? Try it in your browser:
the playground plays every lesson in a real Neovim, exercise by exercise,
with captions and a follow-along mode where you press the keys.
For a longer tour, examples/tutorial.org has
exercises for every feature and examples/00-index.org
a file per area; nvim -u examples/minimal_init.lua examples/tutorial.org
opens it without touching your config or your notes.
mkdir ~/organd open~/org/todo.org.- Type
* TODO Buy milk, press<Esc>, then<leader>osand<CR>to schedule it for today. <leader>oa→aopens the weekly agenda.tchanges the state of the entry under the cursor, and<CR>jumps to it.<leader>oc→tcaptures a new task from anywhere. Finish with<C-c><C-c>or:w.- Press
g?in any org or agenda buffer to list its keymaps.
Tip
All org commands live under <leader>o by default. If another plugin
already uses it, set mappings = { prefix = "<leader>O" }. Coming from
Emacs? C-c C-t, C-c C-s, C-c C-w, C-c C-x C-i and about 150 more
Org keys work out of the box (keymaps).
Recorded in a plain Neovim with only org.nvim installed, from the tapes in
docs/media/tapes (config:
docs/media/demo/init.lua). The box in the
bottom-right corner shows the key being pressed.
TAB / S-TAB cycle a subtree / the file like Emacs, M-k / M-j move a
subtree, M-RET adds a heading at the right level, M-h / M-l promote
and demote, <leader>ohs sorts and <leader>ohn narrows.
Ticking a checkbox updates the [2/4] and [50%] cookies of its parents;
marking a task DONE can log a CLOSED: timestamp. Set the state with cit
or <leader>oS, the priority with <leader>o,.
S-Right / S-Left cycle the bullet style, M-RET / M-S-RET add an
item or a checkbox item, M-Up / M-Down move an item and renumber, and
<leader>o- turns plain lines into a list.
<leader>ot opens fast tag selection with mutually exclusive groups,
<leader>oxe sets the effort and <leader>op any property.
<leader>os / <leader>od open a floating calendar where you can type
fri 14:00, +2w or w39; S-Right, <C-a> and <C-x> change a date
in place, and <CR> on it opens that day's agenda.
<leader>oa → a opens the week (or the day): a time grid, a
current-time line, deadline countdowns, overdue items and habit graphs, as
in Emacs. Change states, reschedule, clock in, refile, filter and run bulk
actions from it.
The week view
The dispatcher has the other Emacs views too: every TODO (t), a
tags/property match (m) and a word search (s).
<leader>oc in any buffer, pick a template, type, and finish with
<C-c><C-c> or :w. It's filed under a headline, an outline path or a
date tree (templates).
<leader>or moves a subtree under another heading; <leader>o$ archives
it to <file>_archive with its context in ARCHIVE_* properties.
Tables align themselves, and #+TBLFM formulas run on a Calc-compatible
evaluator. Rows and columns can be inserted, moved and deleted with the
formulas rewritten to follow, sorted and transposed.
<C-c><C-c> on a source block runs it asynchronously and writes the output
back: Python, shell, Lua, Node, Ruby, R, Go, SQLite and more, with :var,
:noweb, :cache, #+CALL, :session REPLs and tangling. <leader>o'
edits a block in its own buffer with the language's filetype.
<leader>oxi clocks in (the statusline shows
the total against the effort), <leader>oxr inserts a clock table that
matches Emacs, and <leader>oC opens column view.
<leader>oxv shows image links as images and <leader>oxl renders LaTeX
fragments, with Neovim 0.13's vim.ui.img in kitty, Ghostty or WezTerm, or
snacks.nvim / image.nvim elsewhere (where previews
work).
<leader>o. (C-c C-j) jumps to a heading of the file, <leader>og to
any heading of your agenda files, through your picker of choice
(pickers).
Relative timers for meeting notes (<C-c><C-x>0, <C-c><C-x>-), a
countdown for the current entry (<C-c><C-x>;), and reminders before
timed agenda entries with notifications.enabled.
<leader>oif inserts a footnote, :Org lint lists a file's problems in
the location list, and with use_speed_commands = true single letters at
the start of a heading run commands, like Emacs's speed keys.
<leader>ols stores a link, <leader>oli inserts it, <CR> follows it.
<leader>o/ folds the file down to TODOs, a regexp, a tag match or
deadlines.
<leader>oe opens the export dispatcher: HTML, LaTeX, Beamer, KOMA
letter, man page, Markdown, ASCII, Org, iCalendar, ODT and Texinfo are
ports of Emacs's back-ends, pandoc handles DOCX and EPUB, and :Org preview shows a live HTML preview.
Press g? in any org or agenda buffer to list every keymap there, grouped
by topic, with each command's Vim and Emacs keys on one row.
| Area | Highlights | |
|---|---|---|
| 🌳 | Outline | Headline folding with Emacs-style TAB/S-TAB cycling, #+STARTUP and VISIBILITY visibility, archived subtrees that stay folded, motions (]] [[ g{), text objects (dar, vic, ci-, daL, ...), and . repeat |
| ✂️ | Structure editing | A context-aware M-RET, promote and demote, move, cut/copy/paste/clone subtrees, sort, narrow, structure templates |
| 📋 | Plain lists | Every bullet style, checkboxes with a [-] partial state, [2/5] and [40%] statistics cookies, renumbering, TAB on a new item to indent it |
| ✅ | TODO | Multiple keyword sequences, fast selection, !/@ logging, LOGGING / LOG_INTO_DRAWER properties, repeaters (+1w, ++1d, .+2d, REPEAT_TO_STATE), ORDERED / NOBLOCKING dependencies, tag triggers, #+TYP_TODO type sequences, priorities |
| 🏷️ | Tags and properties | Fast tag selection with groups, tag changes over a selection, inheritance, #+FILETAGS, property drawers, Effort, _ALL values cycled with S-Left/S-Right |
| 📅 | Dates | A floating calendar that understands +2w, fri 14:00, sep 15 and w39; SCHEDULED/DEADLINE with warning and delay periods; <C-a>/<C-x> on any part of a timestamp, minutes rounded to 5; custom timestamp formats (C-c C-x C-t) in the buffer and in export; Emacs's org-duration units and formats |
| 🗓️ | Agenda | Day to year views, a time grid, habits, log, clock-report, entry-text and archive modes, the full Emacs match syntax, custom composite commands, tag/category/effort/regexp filters, bulk actions, follow mode, restriction lock, PDF/PostScript export, calendar conversions, moon phases, sunrise/sunset and holidays, the Emacs diary file and every diary sexp of Emacs's calendars |
| 📥 | Capture | Grouped templates; entry, item, checkitem and table-line types; file, headline, outline-path, date-tree, regexp, ID, clock and function targets; all the common %-escapes; :unnarrowed captures in the target file, org-extend-today-until for dates, Emacs Lisp %(sexp) escapes |
| 📦 | Refile and archive | Refile or copy subtrees or regions, with Emacs-style target specs, outline-path completion in steps and refile logging; archive to a file, heading, date tree or Archive sibling with the ARCHIVE_* context properties; refile cache; notes in the *Org Note* buffer |
| 🔗 | Links | file: with ::line, ::*heading, ::#id and ::/regex/; id:, <<targets>>, <<<radio targets>>>, coderefs, shell: (with an *Org Shell Output* buffer), elisp:, wildcard file:*.org listings, attachment:, abbreviations, custom types, concealed display, store/insert last/all links |
| ⏱️ | Clocking | Clock in/out/cancel/jump, clock history with default and interrupted tasks, Emacs's clock resolution (keep, subtract, got-back) for dangling clocks and idle time, auto clock-out, effort estimates with an overrun alert, a statusline component, clocktable blocks matching Emacs output (:step, :formula, :sort, :lang…), agenda clock check, relative and countdown timers |
| 🧮 | Tables | Automatic alignment, column shrinking, row/column/cell editing with formula fixing, copy-down, CSV/TSV import and export, #+TBLFM formulas with a Calc-compatible evaluator, a formula editor and debugger, radio tables, orgtbl-mode (including the unicode and table.el translators) and plots (including radar); Calc symbolic algebra (simplify, deriv, integ, solve), vectors and matrices, modulo forms, complex numbers, HMS forms, error forms, intervals and units; table.el grid tables (C-c ~, C-c ', export) |
| 🧪 | Babel | Asynchronous execution in many languages (with a spinner, placeholder results and cancelling), :session as live REPL buffers (shells, Python, Node, Ruby, R, Lua) with :async, inline src_lang{…} blocks and call_name(), :results, :var references that evaluate blocks (name(x=1), slices, other files, IDs), :noweb, :wrap, :cache, :file, #+CALL, Library of Babel, tangling, optional evaluation on export, the C-c C-v commands, and editing a block in its own buffer with C-c '; emacs-lisp blocks run in a separate Emacs when one is installed |
| 📤 | Export | A port of Emacs's export engine (with #+BIND and (eval …) macros): HTML, LaTeX/PDF, Beamer, KOMA letters, man pages, Markdown, ASCII, Org, iCalendar, ODT and Texinfo/Info back-ends matching Emacs output, GitHub-flavoured Markdown, citations with the CSL processor, publishing projects, every #+OPTIONS key, plus DOCX, EPUB and more through pandoc |
| 🖼️ | Images and LaTeX | Image links and LaTeX fragments previewed in place of the link (org-link-preview, -region, -clear, -refresh, org-latex-preview) with Neovim 0.13's vim.ui.img, or snacks.nvim / image.nvim on older versions; org-image-actual-width, #+ATTR_ORG: :width / :align, images as link descriptions, previews on TAB, #+STARTUP: linkpreviews latexpreview, the Emacs LaTeX processes (dvipng, dvisvgm, xelatex, imagemagick) plus tectonic, images in ltximg/, preview functions for custom link types, remote http(s) images |
| 🧩 | Extensions | Optional, off until enabled: slideshows (org-present), queries and saved views (org-ql), linked notes (org-roam), grouped agendas (org-super-agenda), Todoist-style quick add, a guided weekly review, pomodoros (org-pomodoro), flashcards with spaced repetition (org-drill), an in-process language server (symbols, hover, cross-file rename), kanban board, timeline, clock heatmap and Today sidebar, code ↔ notes links and literate Neovim config, Hugo blog export (ox-hugo), a structural git merge driver, iCalendar subscriptions, the org command line, mermaid/dot/plantuml diagrams, live transclusion (org-transclusion) and a dated journal (org-journal) |
| 🎁 | And more | Column view, org-indent mode, speed keys, footnotes, sparse trees, org-lint, entry encryption (org-crypt), org-protocol, inline tasks, org-num, pretty entities, appointment notifications, attachments (with org-attach-git), RSS/Atom feeds (org-feed), MobileOrg, IDs, dynamic blocks, BibTeX links (ol-bibtex), org-ctags, the Org/table/agenda menus and org-mouse, completion, :checkhealth org, a Lua API and a session server |
- The guide: installation in detail, every default key, configuration, capture templates, custom agenda commands, integrations, the Lua API, the differences from Emacs, every extension and the roadmap.
- The manual:
:h org.nvim(doc/org.txt); every option is under:h org-config. - The documentation website: the manual, the guide, the examples and the parity scorecard, searchable.
How much of Emacs Org 9.8 works the same way in org.nvim, measured
against Org 9.8.11 (October 2026). Every interactive command and
every user option of Org 9.8.11 (877 commands and 1,055 options, listed by
Emacs itself, plus the org-overriding-columns-format variable that the
manual tells users to set, and org-replace-buffer-contents, a command
only before Emacs 31) was checked against org.nvim:
| Lens | Parity | What it counts |
|---|---|---|
| Overall | ▰▰▰▰▰▰▰▰▰▰ 99.9% |
The 1,806 commands and options (of 1,934) that can exist outside Emacs; Emacs internals are left out |
| Strict | ▰▰▰▰▰▰▰▰▰▰ 98.6% |
Also counts the 24 that need Emacs itself (Gnus, BBDB, eww, TRAMP, CDLaTeX...) |
Before this round, the same measurement gave 76.6% overall and 74.3% strict. The earlier estimates in this README (~92–95%) weighted everyday features more heavily; this measurement gives every command and option the same weight.
By area:
| Area | Parity | Before | What's left |
|---|---|---|---|
| 🌳 Outline, structure, TODO, tags, properties, dates | ▰▰▰▰▰▰▰▰▰▰ 100% |
77% | Nothing that Neovim can do; CDLaTeX, RefTeX and speedbar need Emacs (98% strict) |
| 📋 Plain lists | ▰▰▰▰▰▰▰▰▰▰ 100% |
61% | — |
| 🗓️ Agenda and habits | ▰▰▰▰▰▰▰▰▰▰ 100% |
83% | — |
| 📥 Capture and date trees | ▰▰▰▰▰▰▰▰▰▰ 100% |
71% | — |
| 📦 Refile and archive | ▰▰▰▰▰▰▰▰▰▰ 100% |
91% | — |
| ⏱️ Clocking and timers | ▰▰▰▰▰▰▰▰▰▰ 100% |
91% | — |
| 🧮 Tables and plots | ▰▰▰▰▰▰▰▰▰▰ 99.6% |
88% | Calc's symbolic mode and date format can't be set in calc_default_modes |
| 🏛️ Column view | ▰▰▰▰▰▰▰▰▰▰ 100% |
100% | — |
| 🔗 Links | ▰▰▰▰▰▰▰▰▰▰ 100% |
59% | Links to Emacs applications (Gnus, BBDB, MH-E, eww, w3m) need Emacs (84% strict) |
| 📎 Attachments, IDs, footnotes, lint, protocol, crypt | ▰▰▰▰▰▰▰▰▰▰ 100% |
79% | — |
| 🧪 Babel and source editing | ▰▰▰▰▰▰▰▰▰▰ 99.7% |
58% | Common Lisp runs in sbcl, not SLIME/SLY; TRAMP and Clojure's CIDER need Emacs |
| 📤 Export and publishing | ▰▰▰▰▰▰▰▰▰▰ 100% |
78% | BBDB anniversaries in iCalendar need Emacs |
| 📚 Citations | ▰▰▰▰▰▰▰▰▰▰ 100% |
39% | — |
| 📰 Feeds and MobileOrg | ▰▰▰▰▰▰▰▰▰▰ 100% |
100% | — |
Note
How this is measured. docs/parity/inventory.el
makes Emacs list every command and option of Org 9.8.11, and
docs/parity/inventory.tsv records, for each
one, whether org.nvim does the same thing (with the code that does it), or
why not. A command or option counts as done only when org.nvim behaves
equivalently, with a spec that exercises it; results that Emacs produces
(buffer text, export output, agenda lines) are checked against Emacs run in
batch mode. Partial ones count half; Emacs internals with no user-visible
effect (byte compilation, caches, obsolete aliases) are left out. Run
docs/parity/score.sh to recompute the numbers.
A command or option that exists is not the same as every edge case of it
behaving identically, so this measures coverage, not bug-for-bug
equality. Where org.nvim differs on purpose (prefix arguments are counts,
the cursor sits on a character rather than between two), it says so in
Differences from Emacs Org mode,
:h org-differences and the parity review.
If something behaves differently from Emacs and isn't listed,
please open an issue.
Optional features modelled on popular third-party Emacs Org packages ship
with org.nvim but stay unloaded until you enable them in extensions:
require("org").setup({
extensions = {
present = true, -- enable with the defaults
roam = { directory = "~/roam" }, -- options are merged over its defaults
},
})Each one is ✅ stable (used daily, well covered by specs; changes to its options or keys are called out in the release notes) or 🧪 experimental (works and is tested, but its options may still change):
| ✅ Stable | 🧪 Experimental |
|---|---|
ql, super_agenda, present, roam, quickadd, ics, kanban, sidebar, merge, transclusion, heatmap |
review, pomodoro, drill, cli, diagrams, code, literate, lsp, timeline, hugo, journal |
The guide describes each one with a demo,
the extensions status page shows
how close each experimental one is to stable, and :h org-extensions has
every option.
Contributions of all sizes are welcome: bug reports, docs fixes, new link types, Babel languages, exporters, or anything on the roadmap. Each piece of Org lives in its own small module, and there's a fast headless test suite, so it's easy to get started:
git clone https://github.com/xheisenbugx/org.nvim && cd org.nvim
make test # run all specs headlessly
make test SPEC=tests/spec/agenda_spec.lua # one spec
make lint # stylua --check + source lint rules
make bench # time the first open and a 50,000-headline agendaCONTRIBUTING.md explains how the code is organised
and how to add a feature. CHANGELOG.md lists what changed
in each release.
org.nvim is released under the MIT License.
If org.nvim makes your notes, tasks or agenda better, give it a ⭐. It helps other Neovim users find it.
You can also buy me a coffee on Ko-fi ☕.