Back to catalog
Org-roam
Using
Using
Org-roam
GPL-3.0A Roam Research replica built as an extension for Emacs Org-mode.
Open-source alternative to — compare it against:
Overview
Org-roam 
Org-roam is a plain-text knowledge management system. It brings some of Roam's more powerful features into the Org-mode ecosystem.
Org-roam borrows principles from the Zettelkasten method, providing a solution for non-hierarchical note-taking. It should also work as a plug-and-play solution for anyone already using Org-mode for their personal wiki.
- Private and Secure: Edit your personal wiki completely offline, entirely in your control. Encrypt your notes with GPG. Take lasting notes in plain-text.
- Networked Thought: Connect notes and thoughts together with ease using backlinks. Discover surprising and previously unseen connections in your notes with the built-in graph visualization.
- Extensible and Powerful: Leverage Emacs' fantastic text-editing interface, and the mature Emacs and Org-mode ecosystem of packages.
- Free and Open Source: Org-roam is licensed under the GNU General Public License version 3 or later.
Installation
Down below you will find basic installation instructions for how to quickly
install org-roam using various environments for various purposes. For more
detailed information, please read the manual.
Using package.el
Toggle instructions
You can install org-roam from MELPA or MELPA
Stable using package.el:
M-x package-install RET org-roam RET
Using straight.el
Toggle instructions
Installation from MELPA or MELPA Stable using straight.el:
(straight-use-package 'org-roam)
Or with use-package:
(use-package org-roam
:straight t
...)
If you need to install the package directly from the source repository, instead of from MELPA, the next sample shows how to do so:
(use-package org-roam
:straight (:host github :repo "org-roam/org-roam"
:files (:defaults "extensions/*"))
...)
If you plan to use your own local fork for the development and contribution, the next sample will get you there:
(use-package org-roam
:straight (:local-repo "/path/to/org-roam-fork"
:files (:defaults "extensions/*")
:build (:not compile))
...)
Using Doom Emacs
Toggle instructions
Doom's :lang org module comes with support for org-roam, but it's not
enabled by default. To activate it pass +roam flag to org module in your
$DOOMDIR/init.el (e.g. (org +roam)), save the file and run doom sync -u
in your shell.
To provide better stability, Doom pins the package to a specific commit. If you
need to unpin it (not recommended doing that, request Doom to bump the package
instead) use the next in your packages.el:
(unpin! org-roam)
If for some reasons you want to use a different recipe for org-roam, you can
use the next form in your packages.el to install the package from a recipe
repository (e.g. MELPA):
(package! org-roam)
You can pass :pin "commit hash" to pin the package to a specific commit.
With the next sample you can install the package directly from the source repository:
(package! org-roam
:recipe (:host github :repo "org-roam/org-roam"
:files (:defaults "extensions/*")))
And if you plan to use your own local fork for the development or contribution, the next sample will get you there:
(package! org-roam
:recipe (:local-repo "/path/to/org-roam-fork"
:files (:defaults "extensions/*")
:build (:not compile)))
Without a package manager
Toggle instructions
To install the package without using a package manager you have the next two options:
- Install the package by cloning it with
gitfrom the source repository. - Or install the package by downloading the latest release version.
In both of the cases you will need to ensure that you have all the required dependencies. These include:
- org (9.6 is the minimum required version!)
- emacsql
- magit-section
After installing the package, you will need to properly setup load-path to the
package:
(add-to-list 'load-path "/path/to/org-roam/")
(add-to-list 'load-path "/path/to-org-roam/extensions/")
After which you should be able to resolve (require 'org-roam) call without any
problems.
Org-roam also comes with .texi files to integrate with Emacs' built-in Info
system. Read the manual to find more details for how to install them manually.
Configuration
Here's a very basic sample for configuration of org-roam using use-package:
(use-package org-roam
:ensure t
:custom
(org-roam-directory (file-truename "/path/to/org-files/"))
:bind (("C-c n l" . org-roam-buffer-toggle)
("C-c n f" . org-roam-node-find)
("C-c n g" . org-roam-graph)
("C-c n i" . org-roam-node-insert)
("C-c n c" . org-roam-capture)
;; Dailies
("C-c n j" . org-roam-dailies-capture-today))
:config
;; If you're using a vertical completion framework, you might want a more informative completion interface
(setq org-roam-node-display-template (concat "${title:*} " (propertize "${tags:10}" 'face 'org-tag)))
(org-roam-db-autosync-mode)
;; If using org-roam-protocol
(require 'org-roam-protocol))
Note that the file-truename function is only necessary when you use symbolic
link to org-roam-directory. Org-roam won't automatically resolve symbolic link
to the directory.
Getting Started
David Wilson of System Crafters has produced an introductory video that covers the basic commands:
Getting Help
Before creating a new topic/issue, please be mindful of our time and ensure that it has not already been addressed on GitHub or on Discourse.
- If you are new to Emacs and have problem setting up Org-roam, please ask your question on Slack, channel #how-do-i.
- For quick questions, please ask them on Slack, channel #troubleshooting.
- If something is not working as it should, or if you would like to suggest a new feature, please create a new issue.
- If you have questions about your workflow with the slip-box method, please find a relevant topic on Discourse, or create a new one.
Knowledge Bases using Org-roam
Contributing
To report bugs and suggest new feature use the issue tracker. If you have some code which you would like to be merged, then open a pull request. Please also see CONTRIBUTING.md.
License
Copyright © Jethro Kuan and contributors. Distributed under the GNU General Public License, Version 3.
