org-mode modules for citations, cross-references, bibliographies in org-mode and useful bibtex tools to go with it.
Clone or download
jkitchin Merge pull request #600 from plantarum/master
clarify documentation of org-ref-default-bibliography
Latest commit f58b8d5 Sep 17, 2018
Failed to load latest commit information.
citeproc Prefer cl-lib to cl Jan 30, 2018
screenshots replace screenshot. add text to screenshots. Jan 16, 2016
test Prefer cl-lib to cl Jan 30, 2018
tests added issue 482 files Oct 27, 2017
.ert-runner try to get ert-runner setup for testing. Feb 28, 2016
.gitignore add init file an update makefile for testing Jun 30, 2016
.travis.yml fix typo in travis.yml Jun 3, 2018
Cask Try to fix travis for newer Emacs versions Jan 22, 2018
Makefile testing: use cask build to compile org-ref Jan 22, 2018 update README configuration Jun 5, 2018 add development file Jun 1, 2017
doi-utils.el Updated ACM to allow HTTPS Jun 12, 2018
nist-webbook.el Add org-ref-link-set-parameters macro for org compatibility Feb 28, 2017
org-ref-arxiv.el declare functions to clean up a few compiler warnings Jun 3, 2018
org-ref-bibtex.el whitespace cleanup. Aug 3, 2018
org-ref-citeproc.el Declare functions and variables to satisfy byte compiler Jan 10, 2018
org-ref-core.el Added documentation for org-ref-default-bibliography Sep 14, 2018
org-ref-glossary.el declare functions to clean up a few compiler warnings Jun 3, 2018
org-ref-helm-bibtex.el Fix issue reported in tmalsburg/helm-bibtex#250. Jul 4, 2018
org-ref-helm-cite.el Prefer cl-lib to cl Jan 30, 2018
org-ref-helm.el Fix for issue #560 Mar 21, 2018
org-ref-isbn.el Fix wrong variable name May 19, 2017 update the issues file. May 9, 2017
org-ref-ivy-cite.el Prefer cl-lib to cl Jan 30, 2018
org-ref-ivy.el rm comment Jul 2, 2016
org-ref-latex.el defvar for byte-compiling Jun 29, 2016
org-ref-pdf.el Prefer cl-lib to cl Jan 30, 2018
org-ref-pubmed.el Fix issue #589. Jul 6, 2018
org-ref-reftex.el Fix typo reported in issue #579 May 18, 2018
org-ref-sci-id.el Add org-ref-link-set-parameters macro for org compatibility Feb 28, 2017
org-ref-scifinder.el Autoload interactive functions. Jan 29, 2016
org-ref-scopus.el Merge pull request #395 from marsam/feature/org-set-parameters-macro Mar 1, 2017
org-ref-url-utils.el Prefer cl-lib to cl Jan 30, 2018
org-ref-utils.el docs and refactor May 11, 2018
org-ref-worldcat.el minor doc change Dec 17, 2015
org-ref-wos.el Add org-ref-link-set-parameters macro for org compatibility Feb 28, 2017
org-ref.bib add new references to bib file. Update org manual Jun 2, 2017
org-ref.el Resolve issue #557. Require htmlize. Mar 19, 2018 Added a section on bibtex export, moved the biblatex instructions Sep 14, 2018 commit to force travis build Feb 28, 2017
x2bib.el fix org-ref to org-ref-core Jun 25, 2016

org-ref: citations, cross-references, indexes, glossaries and bibtex utilities for org-mode

Coverage Status MELPA MELPA Stable

Introduction to org-ref on YouTube.


Here are some annotated images of basic insertion of citations in org-mode. ./screenshots/introduction.png

The links in org-ref are functional. They do things when your cursor is on them, or you click on them, and sometimes when the mouse hovers over them.


Here is an example of a menu of actions you get when you click on a cite link.


org-ref can analyze your org-file and tell you about it, for example if there are bad citations, multiply defined labels, bad reference links, missing bibliography files, etc… You can select each one and it will jump to the location to help you fix it.



Package installation via Melpa

org-ref has been added to Melpa. This is the recommended way to install org-ref as it will also install all the dependencies.

(add-to-list 'package-archives
	     '("melpa" . "") t)
(when (< emacs-major-version 24)
  ;; For compatibility
  (add-to-list 'package-archives '("gnu" . "")))

Then, you should be able to do M-x package-list-packages, find org-ref and install it.

Installation via github

Make sure all the dependencies are installed. Then clone this repo, add it to your load-path.

git clone

Add this to your .emacs file

(require 'org-ref)


You should set these variables. Here is an example of how mine are set in an init.el file.

(setq reftex-default-bibliography '("~/Dropbox/bibliography/references.bib"))

;; see org-ref for use of these variables
(setq org-ref-bibliography-notes "~/Dropbox/bibliography/"
      org-ref-default-bibliography '("~/Dropbox/bibliography/references.bib")
      org-ref-pdf-directory "~/Dropbox/bibliography/bibtex-pdfs/")

You may want to set some convenient keys for working in your bibtex file. These commands operate on the citation key at point.

If you use helm-bibtex as the citation key completion method you should set these variables too.

(setq bibtex-completion-bibliography "~/Dropbox/bibliography/references.bib"
      bibtex-completion-library-path "~/Dropbox/bibliography/bibtex-pdfs"
      bibtex-completion-notes-path "~/Dropbox/bibliography/helm-bibtex-notes")

;; open pdf with system pdf viewer (works on mac)
(setq bibtex-completion-pdf-open-function
  (lambda (fpath)
    (start-process "open" "*open*" "open" fpath)))

;; alternative
;; (setq bibtex-completion-pdf-open-function 'org-open-file)

There are alternative citation key completion methods.

An alternative to helm-bibtex
Uses ivy for key completion
Uses reftex and org-mode for completion (no longer developed)

If you plan to build PDF files via LaTeX you need to make sure that org-latex-pdf-process is set to process the bibliography (using bibtex or biblatex). Here is one example of how to do that (see ./*LaTeX export for other alternatives).

(setq org-latex-pdf-process (list "latexmk -shell-escape -bibtex -f -pdf %f"))

Finally, add this to your init.el files.

(require 'org-ref)

Go forth and citate.

Some other useful libraries in org-ref

Note many of these have been renamed with an org-ref prefix.

Download bibtex entries and PDFs from doi and crossref queries.
Add drag-n-drop PDF to create bibtex entries
Add drag-n-drop urls to create bibtex entries
Utility functions for bibtex
org-ref-like features in LaTeX.
arxiv links, add bibtex entries from
pubmed links, add bibtex entries from PMID.
Add bibtex entries from a book ISBN
WebOfKnowledge links and queries
Scopus links and queries
Convert bibliography formats to and from bibtex
Links to NIST Webbook resources


For more information, see the org-ref manual.

Errors and issues

Please report errors here: issues.


I would like to thank the contributors to org-ref, and everyone who has filed an issue, or asked about org-ref on the org-mode Mailing list.