Org-Drill — Spaced-Repetition Flashcards for Org Mode

Maintenance Status | Features | Installation | Quick Start | In-Session Keys | Configuration | Development | History | License

Org-Drill turns Org Mode headings into flashcards and drills you on them using a spaced-repetition algorithm. You write your cards as plain Org headings, tag them :drill:, and M-x org-drill walks you through the ones that are due. Ratings (0–5) feed a scheduling algorithm (SM2, SM5, or Simple8) that spaces out future reviews.

" Memory is the residue of thought. " — Daniel Willingham

Maintenance Status

This is a maintained fork of phillord/org-drill. The upstream looks abandoned (no commits in a long while, open issues sitting), so I've taken on keeping the project alive — fixing bugs, raising test coverage, modernizing. Recent work includes:

• Fix for the [Y-08-27 Wed 16:%] timestamp shape (upstream issue #59)
• Fix for default-input-method getting clobbered every drill session (upstream issues #52, #58)
• Fix for entries whose answer lives in a child sub-heading being silently skipped (upstream issue #13)
• Fix for cloze face leaking onto org headings (upstream issue #38)
• Fix for "Window system frame should be used" error on TTY emacsclient (upstream issue #44)
• Several other smaller fixes — see git log

If you've been hitting any of those, this fork should help.

Where to get it:

• Primary: github.com/cjennings/org-drill
• Issues / questions: GitHub Issues

Features

• Cards live as Org headings — no separate database, no sync hassle, your decks are just .org files
• Multiple card types: simple front/back, two-sided, multi-cloze, hide-N-of-N, language-specific (verb conjugation, noun declension), and user-defined
• Three spaced-repetition algorithms: SM2, SM5, Simple8 (default)
• Cram mode for review sprints — drill everything, ignore schedule
• Leitner box system as an alternative to the SM* family
• Cloze deletion with optional hints ([hidden||hint])
• Multi-file decks via Org's agenda-files mechanism, or per-directory scope
• Session controls: maximum duration, maximum items per session, leech detection
• Statistics dashboard (M-x org-drill-statistics): overview, daily/weekly trends with sparklines, quality histogram, a needs-attention view (leeches, long-overdue, forgotten-new), and a 7-day forecast, with CSV export
• LaTeX preview, inline images, and the rest of the Org rendering machinery just work inside drill sessions

Installation

Requires Emacs 25.3+ and Org 9.6+. Pick whichever package manager you already use.

MELPA + use-package

Org-drill is on MELPA and MELPA Stable. Add the following to your init file:

(use-package org-drill
  :ensure t
  :commands (org-drill org-drill-cram org-drill-resume)
  :bind ("C-c d" . org-drill))

package-vc-install (Emacs 29+)

Pull straight from this fork's main branch:

(unless (package-installed-p 'org-drill)
  (package-vc-install "https://github.com/cjennings/org-drill"))

use-package with :vc (Emacs 29+)

(use-package org-drill
  :vc (:url "https://github.com/cjennings/org-drill" :rev :newest)
  :bind ("C-c d" . org-drill))

Straight

(straight-use-package
 '(org-drill :type git :host github :repo "cjennings/org-drill"))

Manual

Clone the repo and add it to your load-path:

(add-to-list 'load-path "/path/to/org-drill")
(require 'org-drill)

Quick Start

Sixty seconds from install to first drill:

1. Open a new file my-deck.org.

2. Paste the following and save:

   * What's the capital of France? :drill:
   Paris
   * What's 2 + 2? :drill:
   4
   * What's `M-x` in Emacs?               :drill:
   :PROPERTIES:
   :DRILL_CARD_TYPE: hide1cloze
   :END:
   The keystroke that runs [Execute extended command].
   

3. M-x org-drill.

Org-drill will show you each card, wait for you to think of the answer, and let you reveal it with any key. Rate yourself 0 (forgot) to 5 (perfect) — that rating sets when you'll see the card again.

The bundled org-drill.org file in this repo is also a working drill deck — open it in Emacs and M-x org-drill to see every card type in action. spanish.org is another worked example, oriented at language learning.

In-Session Keys

While a card is shown:

After the answer is revealed:

Anything 3 or higher pushes the card forward in the schedule; 0–2 sends it back. Arrow keys, Page Up, Page Down, and the mouse wheel scroll the visible card during the prompt.

After a quit (q) or edit (e), resume with M-x org-drill-resume. Cram everything in your deck regardless of schedule with M-x org-drill-cram.

Configuration

The most-used customization options:

(use-package org-drill
  :ensure t
  :custom
  ;; Default scope for `M-x org-drill'.  Other choices:
  ;;   'tree (subtree at point), 'directory, 'agenda, a list of file paths.
  (org-drill-scope 'file)
  ;; How long a session may run before org-drill stops queuing new items.
  (org-drill-maximum-duration 20)             ; minutes; nil for no limit
  ;; How many items per session.  nil for everything pending.
  (org-drill-maximum-items-per-session 30)
  ;; Spaced-repetition algorithm.  Choices: 'sm2, 'sm5, 'simple8.
  (org-drill-spaced-repetition-algorithm 'sm5)
  ;; What to do with leech items (cards you keep forgetting).
  ;; Choices: 'warn (show a banner), 'skip (don't drill), nil.
  (org-drill-leech-method 'warn)
  ;; Increase the text size during drill sessions.  nil leaves it alone.
  (org-drill-text-size-during-session 1.5))

The full list of defcustoms is documented inside the source — M-x customize-group RET org-drill RET shows them all.

Development

The repo includes a Makefile that wraps Cask-driven test and lint flows:

Tests live under tests/ as ERT files. Coverage hovers around 78% on org-drill.el and is tracked with the :slow ERT tag for any genuinely-long-running tests.

Issues and pull requests welcome on GitHub.

History

Org-drill started life as a contrib in Org Mode itself (when the Org repo had a contrib/lisp/ directory), authored by Paul Sexton. It later moved to its own GitLab repo under Phil Lord when Org dropped contrib. Phil's repo carried the project through several years of fixes and feature additions.

This fork picks up where Phil's repo paused. Bug fixes are landing here, test coverage is climbing, and the project is being modernized for current Emacs and Org versions.

For the deep manual — every card type, every customization, plus a working deck you can drill against to see each card-type in action — open org-drill.org in Emacs.

License

GPL-3.0-or-later. See the header of org-drill.el for the full notice.