How to set up Sublime Text to be able to render open R Markdown documents.
You need to have R installed on your computer
On Ubuntu you can do this from the terminal with:
$ sudo apt install r-base-core
On macOS, download RStudio from its website
Check that it’s worked from the terminal with:
$ R --version
You also need to have the R package rmarkdown
installed. This can be done by opening R (eg by running R
in the terminal) and executing:
install.packages("rmarkdown")
If you will be running Python chunks in your R Markdown files you will also need to have the reticulate package:
install.packages("reticulate")
It might also be useful to have the libpython
Ubuntu
package, see the “Additional Setup” note below.
Pandoc must also be installed
On Ubuntu you can get this from the terminal:
$ sudo apt install pandoc
On macOS it can be downloaded from its website
Check that you have it from the terminal with:
$ pandoc --version
Install the R-IDE and LSP packages in Sublime Text:
Check that it has worked by opening an R Markdown file (one with
.Rmd
as the extension) in Sublime Text and seeing if the
syntax highlighting is working. The current syntax highlighting is
displayed in the bottom right-hand corner and can be changed by
selecting it and choosing “R-IDE” > “R Markdown”.
Additional Setup for Python Users
If you run Python code in R Markdown it will use the
python3
command in the background (ie it will use the same
version of Python as when you run python3
in a terminal).
This may be exactly what you want, in which case you can skip ahead. If
you have multiple versions of Python installed, however, you might want
to use a different version to that associated with python3
,
for example you might want to use Python 3.13 which is associated with
the terminal command python3.13
. That can be achieved by
adding the following chunk in your R Markdown file:
```{r, echo = FALSE}
library(knitr)
opts_chunk$set(engine.path = "/usr/bin/python3.13")
```
However, with some versions of Python (eg 3.11) this might result in the following error:
Error: '/usr/bin/python3.11' was not built with a shared library.
reticulate can only bind to copies of Python built with '--enable-shared'.
As mentioned in the error message, your Python does not have a shared library. If you install Python from source (eg if you are on Ubuntu and you downloaded it from the Python website) you should do so with the following step as part of the process in order to create a shared library:
$ ./configure --enable-shared
On Ubuntu, if you install Python a different way (eg by using
apt
) then you can download the shared library
libpython
as an Ubuntu
package, eg libpython3.11
for Python 3.11:
$ sudo apt install libpython3.11
To start with – just to check that it works – use R-IDE to render an R Markdown file:
.Rmd
as the
extension) in Sublime Text and have it active (click inside it to place
your cursor there)output
parameter in the R Markdown file’s YAML
configuration (eg output: html_document
will give you an
HTMl file)Now check to see if you can do this rendering by invoking a Sublime Text “Build System”:
No Build System
in the
lower left-hand corner you will need to create a Build System
manuallyCreating an R Markdown Build System Manually
From the menu bar, go to “Tools” > “Build System” > “New Build
System”. In the untitled.sublime-build
file that appears,
replace everything with:
{
"cmd" : ["Rscript", "-e", "rmarkdown::render('$file')"],
"selector" : "text.html.markdown.r"
}
Note: the
"selector"
line is needed for this Build System to be associated with files that are within the R Markdown scope. To check what scope a file is in, go to “Tools” > “Developer” > “Show Scope Name” (Ctrl+Shift+Alt+P) while the file is active
Save this file as R Markdown.sublime-build
in the
default location.
For the record, these default locations are:
- Ubuntu:
/home/<username>/.config/sublime-text/Packages/User
- macOS:
/Users/<username>/Library/Application Support/Sublime Text 4/Packages/User
The parent folder (“Packages”) can be opened via “Preferences” > “Browse Packages…”
Now you should be able to render your R Markdown file with the Build System:
Now try to build the file again using the “Automatic” Build System.
If you get the No Build System
outcome it means that the R
Markdown Build System is working but Sublime Text has simply not
associated it with .Rmd
files: change the
"selector"
line in your sublime-build
file so
that it reflects the top-level scope of R Markdown
files (go to “Tools” > “Developer” > “Show Scope Name”
(Ctrl+Shift+Alt+P) while the file is active to see what this is).
If it works, it means that from now on you can just build R Markdown files with “Tools” > “Build” (Ctrl+B/Cmd+B) every time.