FAQ and troubleshooting

Common questions and problems, each with a pointer to the full story. Run :checkhealth org (org-health) first: it finds many of them for you.

The <leader>o keys clash with mine

Every default key written <prefix>... in this manual uses mappings.prefix, by default <leader>o. The global keys (<prefix>a agenda, <prefix>c capture, <prefix>ls, <prefix>g, the clock keys) are set in every buffer, replacing a global mapping made earlier on the same keys; the others are local to org buffers and shadow your <leader>o... mappings there. A mapping of yours on <leader>o itself makes Vim wait 'timeoutlen' for the longer org keys. Move them all to another prefix:

require("org").setup({ mappings = { prefix = "<localleader>o" } })

or change single keys (false removes one), or turn every default key off with mappings.disable_all = true (org-keymaps). :verbose nmap <leader>o shows who set a key.

The agenda is empty

agenda_files defaults to {}, like Emacs's org-agenda-files (nil), so the agenda reads no file at all, not even the current one, until you list some:

require("org").setup({ agenda_files = { "~/org/**/*.org" } })

A directory adds the .org files directly in it, not those in its subdirectories: use a glob like the one above for those. <C-c>[ in an org buffer adds that file to the list (the change is saved), and < in the agenda dispatcher restricts a view to the current file. :checkhealth org says how many files agenda_files gives and why an entry gives none. See org-agenda.

Using it with nvim-orgmode or Neorg

nvim-orgmode: don't keep both. They both define the org filetype and the :Org command, and :checkhealth org warns when it finds nvim-orgmode. Your files need no change: remove nvim-orgmode and convert its setup with :Org migrate_config; org-migrate maps its options and keys to org.nvim's.

Neorg uses its own format, .norg files with the norg filetype, which org.nvim never touches, so the two can be installed side by side. Neorg notes are not Org files, though: org.nvim doesn't read them and they don't show in the agenda.

A source block can't find its interpreter

Each language runs the program in babel.languages.<lang>.cmd: python3 for python, node for js, Rscript for R, bash for bash, ... (lua runs inside Neovim). :checkhealth org lists each of these programs and whether it is found. Point a language at another program; the language tables are merged, so only cmd changes:

require("org").setup({
  babel = {
    languages = { python = { cmd = "/opt/homebrew/bin/python3.12" } },
  },
})

python = false removes a language. The program must be on Neovim's $PATH, which may be shorter than your shell's when Neovim is started from a desktop launcher. See org-babel and org-babel-languages.

Export needs pandoc or LaTeX

HTML, Markdown, ASCII, Org, ODT, iCalendar, Texinfo, man and the LaTeX and Beamer source are written by org.nvim itself. Programs are needed for:

:checkhealth org checks pandoc, makeinfo and the LaTeX compiler. See org-export and org-export-backends.

Captures end up in ~/.notes

A template without target (or with target = ""), and the default "Task" template used while capture.templates is empty, files into default_notes_file. Its default is ~/.notes, as in Emacs (org-default-notes-file), not a file in org_directory. org_directory (default ~/org) is the base of relative paths: target = "inbox.org" is ~/org/inbox.org. Set both:

require("org").setup({
  org_directory = "~/org",
  default_notes_file = "~/org/refile.org",
})

See org-capture-templates.

Windows

org.nvim runs on Windows; org-windows lists what differs. In short: sh/bash source blocks need a bash on %PATH% (Git for Windows, MSYS2), org-crypt needs GnuPG for Windows (or Gpg4win) on %PATH%, reminders are shown through powershell.exe, and TZ with a zone name has no effect.

Why does org.nvim do X differently from Emacs?

org.nvim follows Emacs Org 9.8: the same file format, commands, options (named after the Emacs variables) and defaults. What differs on purpose is in org-differences; org-migrate-differences compares with nvim-orgmode. A difference listed in neither is likely a bug: report it with :Org bug_report (org-bug-report).

Images don't show

Image links are previewed on demand: <prefix>xv (link_preview, Emacs C-c C-x C-v), or when a file opens with ui.images.startup = true or #+STARTUP: inlineimages. Previews need a terminal that can draw images and, depending on the Neovim version, snacks.nvim or image.nvim; tmux, zellij and SSH get in the way. org-images-troubleshooting has the setups that work, and :checkhealth org shows which backend is used.

Keys like <C-CR> or <S-CR> do nothing

The terminal must send them: they need extended keys (CSI u), which tmux passes on only with set -s extended-keys on, and the terminal's own keybinds must not take them. On macOS, Option must send Alt for the <M-...> keys. :checkhealth org checks this in tmux, Ghostty, kitty, WezTerm and Alacritty (org-health). Every such key can be moved (org-keymaps).