1.1 How many versions of R for macOS?

There is only one version of R for macOS. However, R on macOS can be used either on the command-line as on other Unix systems, or via the R.APP GUI (see R.app). The second approach is mostly preferred by Macintosh users.

1.2 What machines does R for macOS run on?

64-bit Intel-based Macs, that is any machine made since mid 2008.

As from R 4.1.0 there is a separate build for ARM-based Macs (known as ‘M1’ and ‘Apple Silicon’), although the Intel-based distribution works well under ‘Rosetta’ emulation.

1.3 How can R for macOS be obtained and installed?

R is available on CRAN in the form of an Installer package containing the R framework and the R.APP GUI. The package is usually named R.pkg with an optional version number.

The installation is done by double-clicking on the Installer package. The Installer will guide you through the necessary steps. Note that it will require password or login of an account with administrator privileges. The installation can be customized, but the default is suitable for most users.

Snapshots of the R-patched and R-devel flavours are available at http://mac.R-project.org/, packaged in the same way.

Further details, including uninstallation and building R from the sources, are in the ‘R Installation and Administration Manual’.

2.1 How to get R.app

R.APP is part of the binary distribution of R for macOS available from CRAN. That distribution consists of one package containing the R framework and R.APP.

Development versions of R.APP are made available on daily basis in the form of a disk image containing the R.APP itself. See the macOS pages on CRAN for detail how to obtain such snapshots (currently at http://mac.R-project.org/).

2.2 How to install the R.app

R.APP is installed the same way as the R framework, namely using binary package provided on CRAN. The bin/macosx directory of a CRAN site contains a standard Apple installer package named R.pkg (optionally containing the version number). Download and double-click the package icon.

Please, carefully read the note on the usage of tcltk and Fortran on the bin/macosx directory of a CRAN site.

2.3 The R Console

In this section you’ll find general information on the R.APP. For specific R tasks that can be done via the R.APP using menus you should read below (see The Menus).

• The Input and the Output
• Copy and Paste
• The current and startup working directories
• Resizing the R Console
• R Console text colors

2.4 General Features

• Editor
• Editor undo and line numbers
• Editor text completion
• Editor function list
• Editor syntax coloring
• Editor (internal and external)
• Editor help
• Drag & drop
• Help system
• History
• Authentication and .libPaths

2.5 The Menus

• Application Menu
• File Menu
• Misc Menu
• Misc Menu
• Workspace Menu
• Packages Menu
• The Help Menu

2.6 Preferences

You can set several aspects of the R GUI via preferences. You can access the Preferences window via the Application menu when the R Console is open.

• Startup

2.7 R.app Bugs

On Unix systems a bug report can be generated using the function bug.report(). Alternatively the bug report can be submitted to the Web page at http://bugs.R-project.org/.

Before you file a bug report, please try to reproduce it using both R.APP and the console version of R (if applicable). If the bug if R.APP-specific, please report the bug to the mailing list R-SIG-Mac@R-project.org instead. Please do NOT forget to mention the exact R.APP version and include the output of sessionInfo().

In any circumstances, in case of a crash, please report the crash.log for the R.bin and/or R.app application. You can get this crash.log using the Console.app located inside /Applications/Utilities (select ‘1’ in the crash menu in the R console at the time of the crash (if you see that menu) to generate a crash report).

3.1 Which kind of packages can I install using the GUI

GUI provides direct access/download/installation of packages located on CRAN, the Bioconductor repositories or a custom repository. You can also install packages from local files, either binary of source packages, as explained below. Otherwise you can use the appropriate R commands (see install.packages) to install packages from a specific location other than the above mentioned ones.

3.2 Installation of packages

R for macOS recognizes packages in two forms: binary packages and source packages.

Binary packages are R packages in ready-to-use form, such that no additional tools are necessary for their use. Binary packages are specific for a given R version OS. CRAN and Bioconductor repositories offer R packages in binary form for the last released R version. Unlike on other Unix systems, CRAN R for macOS installs binary packages by default, i.e. install.packages will look first for binary repositories unless instructed otherwise.

Source packages are general in that they can be used on any platform and OS supported by R, but they need to be processed and/or compiled before they can be used. Additional tools may be necessary for that, see see Installation of source packages for details. For most users binary packages are sufficient (if available and current).

On macOS packages can be installed in three ways:

• Using Package Manager in the R.APP GUI (recommended for most Mac users)
• Using install.packages command in R
• Using R CMD INSTALL command in the shell (aka Terminal)

The latter two methods are common to all Unix systems and as such described in the general R documentation. In the following we will concentrate on using the Package Installer.

If you decide to install packages you should use the Packages & Data menu of the GUI, in particular the sub-item Package Installer. Select the repository, package type (binary or source) and press Get List. This will connect to the repository through the Internet and a list all packages available for installation. The list tells you if a package is already installed on your system, the version of the package available on CRAN and the version of the same package if already installed.

You can use the search field to narrow the list of package to those matching your search criteria. Additionally you can use the search list menu to list only packages that are already installed on your system which is useful for comparing versions of available and installed packages. Finally, you can filter down to packages that have been installed by a previous R version as to allow a simple upgrade.

Select any package you want to install and press the Install button. You can follow the progress of the installation in the R Console. Once the required packages are installed, the list is re-loaded to reflect the versions of newly installed packages.

If you want to update all packages to the latest version, select the repository to use for the packages and press Update All. R will automatically determine the list of packages that can be updated and present you with a selection of packages to update.

You can also download any other package from the Internet yourself and decide to install it from source. In such case select one of the local entries in the top left list and press the Install button (which is now enabled).

Packages can also be installed from other repositories by selecting Other Repository source. Enter the repository URL in the adjacent field. Note that currently the Package Installer assumes that custom repositories maintain proper hierarchy for both source and binary packages the same way CRAN does when using Other Repository. If your custom repository is flat, select Other Directory URL in the installation type list.

3.3 Installation of source packages

Source packages which do not contain compiled code can (with rare exceptions) be installed with no additional tools.

Packages with compiled code (or some with Unix scripts) need the tools used to build R itself discussed in the ‘R Installation and Administation Manual’, and these will need to be in the ‘PATH’ as seen from R.APP or command-line R. For R.APP you may need to add e.g. /usr/local/bin and it is usually most convenient to use command-line R.

If using a CRAN binary install of R the compilers may not be in the same place or have the same names as on the CRAN build machine. Look at file /Library/Frameworks/R.framework/Resources/etc/Makeconf, which will contain lines like

CC = clang -mmacosx-version-min=10.13
CXX = clang++ -mmacosx-version-min=10.13 -std=gnu++14
FC = gfortran -mmacosx-version-min=10.13
OBJC = clang -mmacosx-version-min=10.13
OBJCXX = clang++ -mmacosx-version-min=10.13

(for Intel, similar for ARM). You can either edit that file, or override settings in file ~/.R/Makevars: see the section ‘Customizing package compilation’ of the ‘R Installation and Administration Manual’.

3.4 Where are the packages I’ve installed?

The main library of packages is the one located inside the R.framework (in /Library/Frameworks/R.framework/Resources/library). This library contains the packages (base and recommended ones) distributed along with R. Only administrators are allowed to install packages in this system-wide directory. Note that this directory is R-version-specific. Optionally users can install personal packages in their ~/Library/R/x86_64/x.y/library directory where x.y denotes the R version without the patch level (such as 3.0) – see the startup preferences in R.APP. (For ARM, replace x86_64 by arm64.)

The Package Installer performs installation to either place depending on the installation target setting. The default for an admin users is to install packages system-wide, whereas the default for regular users is their personal library tree.

If you use install.packages R function instead of the Package Installer, the regular Unix behavior applies (see help pages for details). For default setup this means that the packages are installed according to the startup preference setting. You can check the current defaults by issuing

.libPaths()

4.1 AppleScript support

R has partial support for Apple-Scripts. At the moment R can be invoked and asked to run commands from an AppleScript script. What follows is an example of script that interacts with R. It first invokes R and then sends commands to R with the cmd applescript command.

set CommandLine to "R.Version()"
try
	tell application "R"
		activate
		with timeout of 90000 seconds
			cmd CommandLine
			cmd "Sys.getenv()"
			cmd "print(\"HelloWorld!\")"
		end timeout
	end tell
end try

In the above, cmd is the (only) applescript command in the R dictionary that is used to tell R to execute an R command in the R Console. The syntax is

cmd <command string>

where command string have to be in quotes. Actually, the output of the command is not sent back to the application that is calling R but to the R Console directly.

There are some issues. The first is that if R is still not running, it will take a while (depending on how fast your machine is) to startup. In the meanwhile the script sends commands without waiting and it could happen that some commands are missed by R, i.e. they arrive before R is ready to receive applescript commands. The second issue, is that it could be that the applescript calls a bad version of R. This could happen if you have an old version of R (for example the old Carbon R) installed on your System.

As an example, we report here a small script that asks R to source a file using a file dialog.

set file_to_source to (choose file with prompt "Choose file to source") as alias

try
	tell application "R"
		activate
		with timeout of 90000 seconds
			cmd "source(\"" & file_to_source & "\")"
		end timeout
	end tell
end try

4.2 External editors

R accepts the Apple Event command open. This means than an external editor can communicate with R sending portions of R code to execute via files. This is the approach used by the R-Tcl Mode in Alpha X (see http://www.kelehers.org/alpha/).

4.3 Finder actions

Dragging a file on the R icon, causes R to source this file via the source R command or, if the file is an R image data file RDX1 or RDX2 (normally files with extension .rda or .RData), the data is loaded in the workspace and every object with the same name in the workspace is overwritten without notice. Loading a data file is equivalent to the R command load. At the moment there is no control over the file types, i.e. dragging wrong files (i.e. files that are not R scripts or image data) simply gives an error. It is up to the user to do the right thing.

If R is not yet running this action causes R to startup.

5.1 Interactive mode

The quartz device allows for interaction. You can use both identify and locator functions. To break the sequence you should right/control-click or hit the ESC key.

5.2 Saving the image

You can save the content of the quartz device window into a PDF file, via the R menu when the device window has focus. This is a simple way to export high quality graphics from R into other applications on macOS as graphics is PDF-based (so are almost all applications available). For other solutions, see (see Copying the image into the clipboard) and the quartz.save function.

5.3 Copying the image into the clipboard

You can copy the content of the quartz device window in the clipboard to make the resulting image available for pasting into other applications. The clipboard will contain both a PDF version and a bitmap version of the quartz device window. Which version will be used depends on the pasting applications, most modern application will prefer the PDF version which is of higher quality as it supports vector graphics.

8.1 Apple Developer Connection

The Apple Developer Connection (can be reached at http://developer.apple.com) is the main source of information for Apple products (OS, hardware, software) for developers. You can subscribe for free to ADC and get the latest up-to-date tools from Apple (compilers for example): however more recently these have been distributed through the App Store.

8.2 The R for macOS Developer page

There is a page dedicated to development versions for R for macOS. This page is located at http://mac.R-project.org/ and is maintained by Simon Urbanek. It contains latest nightly builds of R and R.APP as well as information on tools necessary to build R.

10.1 How can I have a per session .Rprofile?

You can by writing a .Rprofile file in your favorite session directory and change accordingly the startup working directory using the Preferences (see The current and startup working directories).

10.2 What happens if I drag a file on the R icon?

In this case R will try to source this file or load the image data file (see Finder actions). If R is not yet running it will be launched.

10.3 How can I interrupt lengthy operations or output?

In R.APP you can use the the Stop toolbar button or the ESC (escape) key in the console window to interrupt a running calculation or output.

For the command line version the same is achieved by pressing Ctrl-c. Both applications honor the INT signal, i.e. you can type the following in a separate Terminal window to cancel all R computations:

killall -INT R

(There may be some delay in stopping as R queues reacting to interrupts until safe points in the code.)

However, if the executed code does not check for interrupts (using ‘R_CheckUserInterrupt’) there may be no way of stopping R. In that case it may be worth alerting the maintainer of the package to allow interruption (if appropriate).

10.4 I see spurious error messages when starting R!

If you see error messages upon start of the R GUI which contain Library/InputManagers anywhere in the text, then you have some broken haxxies installed in your system. Those messages do NOT come from R, so don’t blame us. Bundles located in Library/InputManagers of your home (or system) are hacks that get loaded into every Mac application that you start. In most cases you don’t see them crashing, because most applications don’t show the console output, but R does, so all the errors those hacks are causing become visible. The easiest remedy is to delete all offending bundles (possibly the whole Library/InputManagers folder) and get a fixed version of the hack (if you need it). The most common cause for broken hacks is system upgrades (e.g. you get a new Mac and you transfer you settings which include those hacks that are incompatible with your new Mac).

If you want to disable all external error output in the GUI, use

defaults write org.R-project.R 'Ignore stderr' YES

in the Terminal. Note, however, that this will disable all error output from external programs including package installation or the system command.

10.5 Which BLAS is used and how can it be changed?

The BLAS library used by R depends on the way R was compiled (see ‘R Installation and Administration’ manual for details). Current R binaries supplied from CRAN provide both vecLib-based BLAS and reference BLAS shipped with R. vecLib is a part of Apple’s Accelerate framework which provides an optimized BLAS implementation for Mac hardware. Although fast, it is not under our control and may possibly deliver inaccurate results.

The CRAN binary uses --enable-BLAS-shlib option and two Rblas shared libraries are supplied: libRblas.vecLib.dylib which uses vecLib BLAS and libRblas.0.dylib which uses reference BLAS from R. A symbolic link libRblas.dylib determines which one is used. Currently the default is to use the R BLAS: this is recommended for precision.

In order to change which BLAS is used, change the libRblas.dylib symlink correspondingly – for example in Terminal:

cd /Library/Frameworks/R.framework/Resources/lib

# for vecLib use
ln -sf libRblas.vecLib.dylib libRblas.dylib

# for R reference BLAS use
ln -sf libRblas.0.dylib libRblas.dylib

This feature is only present in the R CRAN binary. Ordinarily compiled R from sources will only have one of the above BLAS libraries, corresponding to the configuration options used.

The BLAS library used is displayed in sessionInfo().

10.6 I don’t see a thing when installing packages!

The output is not produced continuously during the package installation. R.APP does its best to display the output as soon as possible, but for example the documentation script does not print anything until done.

Also note that the development build of R.APP sends output to the error console instead of the screen. You may want to check the Console application in that case.

10.7 Why are there faint lines in image plots?

When plots based on the image() function are exported to PDF, Preview shows very faint grid lines at the edges of the rectangles that create the image. Those lines are a rendering artifact in Preview coming from the combination of anti-aliasing and sub-pixel rendering. They are not really a part of the PDF (zooming in will reveal that they are not a real object which would get larger with zoom) since the rectangles are defined as a gapless coverage of the area. The effect can be circumvented by disabling anti-aliasing in Preview.

We correct for this effect in Quartz when rendering on-screen by snapping all rectangles to pixel boundaries of the screen, but Preview does not.

The same effect occurs in any plot with adjacent, filled polygons without border.

10.8 Why doesn’t R GUI support keyboard shortcut XYZ ?

The R.APP GUI uses Apple frameworks for text editing and thus the behavior of text views (console, editor, etc.) is consistent with other applications and allows a very flexible customization. For example if you are not satisfied with the default Emacs-like key bindings that macOS provides, Apple allows you to extend them arbitrarily. For more details see Apple’s documentation on Key Bindings. There are also many 3rd-party pages on key bindings customization, search for StandardKeyBinding.dict.

10.9 What is the difference between the CRAN build and a vanilla build?

The CRAN build of R is slightly different from a vanilla build of R, i.e., a simple ./configure && make && make install. The default package type for all builds compiled from sources is "source" wheres CRAN uses binary packages. Only the CRAN build is guaranteed to be compatible with the package binaries on CRAN (or Bioconductor). The exact flags used by CRAN are avaiable in the R SVN repository of the CRAN build system as conf.xxx files. For R 4.0.0 and higher this is https://svn.r-project.org/R-dev-web/trunk/QA/Simon/R4 Also the CRAN build includes libraries that are required to run R inside the framework. Static libraries used by CRAN R and packages are available in https://mac.R-project.org/bin

10.10 Why is R.home() in the R framework not versioned?

In the command line version of R, R.home() always points to the Resources directory symbolic link inside the R framework which points to Versions/Current/Resource which is turn points to the actual home – a versioned directory such as for example Versions/4.2/Resources. This is how framework versioning works in macOS and is defined by Apple (see Framework Anatomy).

Although it is possible to set R_HOME directly to the versioned path in the R shell scripts (and thus be able to run different version in parallel without changing the symbolic link), there are several dangers lurking there so we don’t recommend it. One problem is that building packages from source won’t work. The linker is always linking against the current version of the framework and therefore only the currently active version of R can compile packages. Further, packages may have used the value of R.home() at install time and thus may not work with incorrect setting. Finally, if such an R start script happens to get copied and the R version changes, it will stop working.

10.11 R.app GUI crashes on startup!

If your R.APP GUI crashes on startup, there are two common causes for this: a saved workspace or a corrupted history file. (Another is a mismatch between R.APP and R if either has been updated).

Saved workspaces can contain commands that implicitly load packages which in turn can trigger bugs in packages or feed R with incorrect starting values (especially if it was saved using another R). Try removing or renaming your workspace – it’s called .RData. If you did not change your startup settings, you can e.g. use

mv ~/.RData ~/workspace.RData

to move it aside and load later manually for inspection using load("~/workspace.RData").

Second most common cause of crashes on startup is a history file that was not created using the R.APP GUI. Again, move it aside to see if that’s the issue: for the default file this could be done by

mv ~/.Rapp.history ~/history.txt

Although we are trying to recover from invalid history files, they can still crash R.APP due to issues in the internal handling of strings in macOS. We are currently working on preventing this issue.

If you did both of the above and R.APP still crashes, please select ‘1’ in the menu after the crash (if you get the crash menu in the console) and send us the resulting crash report (see see R.app Bugs above).

10.12 Why is the GUI not saving my history?

R.APP will by default save the history in a .Rapp.history file whereas command line R will use .Rhistory. So the saved history is only used in subsequent R.APP sessions and not command-line R, and conversely.

Note that calling savehistory() in R.APP does not currently save the history of the R.APP session: this means that history() will show an empty window.

10.13 I get “command not found” in the GUI yet it works in the Terminal – why?

When executing system commands (for example directly via system or indirectly via functions that call other programs such as install.packages) the locations in which the shell is looking for programs is governed by the PATH environment variable. That variable may be set differently for R started from an interactive shell and for R started in the GUI. You can use Sys.getenv("PATH") to verify the current setting.

When R is started from a shell (e.g., on the command line of the Terminal), it will inherit settings from that shell. Those are typically modified by shell-specific configuration files, such as .profile or .bashrc. Those apply only to the shell, not to the system as a whole. In addition, some installers (such as MacTeX) will modify global shell settings to make user’s life more comfortable on the command line, but, again, those do not apply to programs not started from the shell – such as GUIs. See Apple Technical Q&A QA1067 for what Apple says about the topic.

In order to standardize your PATH setting in R, you can set it in your .Renviron file (in your home directory – see ?Startup in R for details on how R uses configuration files on startup). This setting will apply to R regardless of how it is started. You can also add more elaborate constructs to .Rprofile instead if you wish to selectively modify the existing PATH variable via Sys.getenv and Sys.setenv.

10.14 I see no text in a Quartz plot!

Typically this means that you have corrupted fonts in your system. Open the Font Book application (in Applications) and check the fonts that you are using (for example the default font in Quartz is currently “Arial”). Corrupted fonts will have no glyphs (text will not appear as it should), remove such fonts.

10.15 I cannot attach debugger to R

R processes installed using Apple installer cannot be attached to by debuggers. This is a limitation introduced by Apple as a security measure. Since January 2020 Apple requires all notarized applications to use “Hardened Runtime” https://developer.apple.com/documentation/security/hardened_runtime and one of the implications is that such processes cannot be tampered with by debuggers. Therefore official R installers have to use hardened runtime as Apple will no longer allow installation of software that is not notarized.

In order to debug R code or packages, you can use R binaries that don’t use hardened runtime and are not notarized. Such binaries are available in tar-balls at https://mac.R-project.org/ and can be installed by unpacking into /, e.g.:

curl -LO http://mac.r-project.org/high-sierra/R-4.2-branch/x86_64/R-4.2-branch.tar.gz
tar fxz R-4.2-branch.tar.gz -C /

If you are not the administrator, you may have to use sudo tar ....

NOTE: R releases since 4.2.0 include an entitlement in the hardened runtime which allows debugging, so the above issue should not occur in R releases since R 4.2.0.