The purpose of this document is to assist people in installing R, RStudio, R packages, and related software. The process should be straightforward and fast ... at least in an ideal world. I have been through this process many times over the years and I don't recall a single instance where I have experienced an error-free installation. Once you encounter errors, the debugging process can be very frustrating and time-consuming. Websites like Stack Overflow are very helpful in solving many of the errors you may encounter. But even that takes time to search for solutions, to understand if and how they apply to your use case, and ultimately the proposed solution may not work for you. Much of the Troubleshooting section is based on advice from Stack Overflow which I have collated, synergised, and streamlined here. It is my hope that this guide saves users hours of frustration.

I plan to update this document periodically. If you use this guide and find any mistakes or have any suggestions, please contact me at earl.w.duncan@gmail.com.

1 Installing R and RStudio

1.1 Installing R

For Windows:

  1. Go to https://cran.r-project.org/bin/windows/base/.
  2. Click on the link at the top of the page, e.g. "Download R 3.6.1 for Windows".
  3. Open the downloads folder and run the downloaded setup file, e.g. "R-3.6.1-win.exe".
  4. Follow the prompts. I suggest installing with the default settings.

This will install the 32-bit version on 32-bit versions of Windows, and both 32-bit and 64-bit versions on 64-bit verions of Windows. A default GUI is also provided with this installation. However, I highly recommend using RStudio which provides a more user-friendly GUI, but being an integrated development environment (IDE), it also provides a lot of helpful tools and features for developing pacakges, markdown documents, etc. To install RStudio, see the instructions below).

For more advanced instructions, refer to the link at the top of the Windows download page.

For MacOS:

  1. Go to https://cran.r-project.org/bin/macosx/.
  2. Click on the first link on the left side of the page under the heading "Latest release".
  3. Open the Applications folder and run the downloaded setup file, e.g. "R-3.6.1.pkg".
  4. Follow the prompts.
    • Click Continue several times.
    • Agree to the terms of the software license agreement.
    • Click Install. You may need to enter the admin user name and password to proceed.

1.2 Installing RStudio

Note: make sure R is installed before installing RStudio.

For Windows:

  1. Go to https://rstudio.com/products/rstudio/download/
  2. Scroll down the page until you see "RStudio Desktop - Open Source License" and click on the Download button.
  3. Open the downloads folder and run the downloaded setup file, e.g. "RStudio-1.2.5033.exe".

For MacOS:

  1. Go to https://rstudio.com/products/rstudio/download/
  2. Scroll down the page until you see "RStudio Desktop - Open Source License" and click on the Download button.
  3. Open the Applications folder, and run the downloaded setup file, e.g. "RStudio-1.2.5033.dmg".

For other operating systems:

  1. Go to https://rstudio.com/products/rstudio/download/
  2. Scroll further down the page until you see "All Installers".
  3. Find the download link that corresponds to your operating system.
  4. Once downloaded, install the setup file.

2 Installing packages

2.1 Installing packages from CRAN

Packages on the comprehensive R Archive Network (CRAN) can be installed using the function install.packages. E.g.

# A single package
install.packages("ggplot2")

# Multiple packages as a character vector
install.packages(c("ggplot2", "gridExtra", "tidyr"))

or installed from the RStudio menu: Tools > Install Packages... .

Sometimes it is necessary to download and install the packages on which your primary package depends, called "dependencies". This can be accomplished by changing the dependencies argument:

install.packages("ggplot2", dependencies = TRUE)

If you see an error message about the package not being available, you may be able to resolve this by explicitly setting the repos (repository) argument. Usually, this will be the main CRAN mirror site:

install.packages("ggplot2", repos = "http://cran.rstudio.com")

For more tips and troubleshooting this type of error, see Section 4.1.1.

Once a package has been installed, you need to load each library. E.g.

library(ggplot2)
library(gridExtra)
library(tidyr)

You can also unload libraries:

detach("package:ggplot2", unload = TRUE)

2.2 Installing packages from source (compressed file)

Option 1:

Install using the install.packages function as follows:

install.packages(filepath, repos = NULL, type = "source")
# or
install.packages(filepath, repos = NULL, type = "win.binary")

where filepath is a string containing the full path and file name, e.g. "C:/tmp.tar.gz" or "C:/tmp.zip".

Option 2:

Install using the RStudio menu:

  1. Tools > Install Packages... > Install from > Package Archive File
  2. Locate the file on your computer > Install

2.3 Installing packages from GitHub

This requires the devtools library to be installed and loaded (from CRAN) first. E.g.

library(devtools)
devtools::install_github("twitter/AnomalyDetection")
devtools::install_github("AckerDWM/gg3D")

Alternatively, you can download and install a package in two seperate steps.

First, download the compressed file from GitHub using utils::download.file, e.g.:

utils::download.file("https://github.com/yihui/testit/archive/master.zip", 
    destfile = "tmp.zip")
# or
utils::download.file("https://github.com/yihui/testit/archive/master.tar.gz", 
    destfile = "tmp.tar.gz")

or download it from the GitHub webpage manually through your browser:

Second, install from the local source file you just saved by following the instructions in Section 2.2.

2.4 Installing packages from a webpage

If the source file is located on a website, you can install it directly from the website using install_url from the devtools pacakge.

library(devtools)
devtools::install_url(source_URL)

where source_URL is a string containing the URL, e.g. "http://wrap.warwick.ac.uk/71934/1/mcclust.ext_1.0.tar.gz".

2.5 Changing the library path

Sometimes you may encounter an error when installing packages to the default library path (directory). Typically, this default path looks like: C:/Program Files/R/R-3.5.2/library. You can check the library path using .libPaths().

Due to folder permission read-write issues, for example, you may want to change this. For illustration, suppose you want to change this to C:/My R Library.

Option 1: Edit the Rprofile.site file

This option should really only be used in conjunction with the default R GUI. For RStudio or other IDEs, this solution probably won't work (or will reset to defaults after restarting the IDE) - see alternative options below.

  1. Locate the Rprofile.site file in the "etc" folder. E.g. C:/Program Files/R/R-3.6.1/etc.
  2. Open Rprofile.site in a rich text editor like Notepad or WordPad.
  3. Add the following line: assign(".lib.loc", "C:/My R Library", envir = environment(.libPaths))

Option 2: Edit the library path using .libPaths()

Append your personal library as the default path: .libPaths(c("C:/My R Library", .libPaths()))

Option 3: Change environment variables

Instructions for Windows 7 (other Windows OS will be similar; for other OS like Linux, see the URL below):

  1. Start menu > Control Panel > System
  2. Advanced system settings
  3. Environment Variables...
  4. User variables for
  5. New...
Variable name: R_LIBS_USER
Variable value: C:/My R Library

Source: https://stackoverflow.com/questions/15170399/change-r-default-library-path-using-libpaths-in-rprofile-site-fails-to-work

4 Troubleshooting

This is a guide to troubleshooting common errors and warnings encountered when installing and loading packages.

Note:

  • 'XXX', 'YYY', and 'ZZZ' are used as placeholder names for packages.
  • '...' is used to suppress text.
  • For the sake of illustration, the version of R is assumed to be 3.6.1.

4.1 Errors

4.1.1 Package not available

package 'XXX' is not available (for R version 3.6.1)

  1. The most common cause is that the name of the package has been misspelled, e.g. you typed "ggplt2" instead of "ggplot2". Correct the package name and try again.
  2. If installing from a repository:
    • If the package is on CRAN, try setting the repository as the main CRAN mirror site: install.packages("ggplot2", repos = "http://cran.rstudio.com"). This will often resolve the problem of workplace firewalls that block CRAN sites.
    • The package may not be in the repository specified, e.g. you tried to install a package from CRAN rather than R-forge. Check the repository is specified correctly, e.g. install.packages("XXX", repos = "http://r-forge.r-project.org").
    • The package may have been removed from the repository. Check by doing an internet search for the package name. E.g. The R package DPpackage was removed from CRAN (http://cran.r-project.org/web/packages/DPpackage/index.html).
  3. If installing from a local source file:
    • Make sure the arguments repos and type are correct: install.packages(filepath, repos = NULL, type = "source")
  4. See https://stackoverflow.com/questions/25721884/how-should-i-deal-with-package-xxx-is-not-available-for-r-version-x-y-z-wa for less common causes.

To check or confirm what repository the package is in:

library(magrittr)       # For the pipe operator, %>%
available.packages() %>% data.frame() %>% subset(Package == "XXX") %>% t()

For example, ggplot2 lies in the CRAN repository (https://cran.rstudio.com). To change the repositories that R will search, use setRepositories().

4.1.2 Package not found

Error in library("XXX") : there is no package called 'XXX'

This happens when you try to load a library that doesn't exist. E.g. library("nonexistent_pacakge_name").

  1. Check the spelling of the package name.
  2. Check that the package has actually been installed.

    • Option 1:

      p <- installed.packages()[,1]
is.element("XXX", p)

    • Option 2: Navigate to your library path (i.e. the directory returned by .libPaths()) and check that there is a folder with the package name. If not, then install the package first.

4.1.3 Failed to install unknown package

Error: Failed to install 'unknown package' from ...:
(converted from warning) installation of package 'XXX' had non-zero exit status

  1. This usually means there are 1 or more unresolved dependencies. Try installing the package again with dependencies = TRUE.
  2. If installing from source, make sure the path to the file is correct.
  3. Try installing the package in R (not RStudio).
  4. Try downloading the package from the repo and installing it from source -- see Section 2.2.

This is a fairly generic error message, and thus it is difficult to offer specific solutions. Read the accompanying text for hints as to the root cause of the problem.

4.1.4 Unable to install packages

Error in install.packages : unable to install packages

This error is usually (always) accompanied by another error message. For example, it may be preceded by 'lib = "..."' is not writable. Please refer to the troubleshooting for the accompanying error message.

4.1.5 Package or namespace load failed

Error: package or namespace load failed for 'XXX':
  .onLoad failed in loadNamespace() for 'YYY', details:
    call: ...
    error: '...' is not an exported object from 'namespace:ZZZ'

or

Error: package or namespace load failed for 'XXX':
  package 'ZZZ' was installed by an R version with different internals; it needs to be reinstalled for use with this R version

or

Error: package or namespace load failed for 'XXX' in loadNamespace(...):   namespace 'ZZZ' 0.3.0 is already loaded, but >= 0.4.0 is required

These errors indicate a compatibility issue, where package 'XXX' requires an updated version of package 'ZZZ', but the latter is not being updated. (Ignore the intermediate package 'YYY'.)

  1. Try installing the package 'XXX' again with dependencies = TRUE.
  2. Try (re)-installing package 'ZZZ' and its dependencies manually, e.g. install.packages("ZZZ", dependencies = TRUE).
    • Note: if prompted to install one or more packages from source, choose Yes.
    • If installed successfully, first load the package using library(ZZZ) before trying library(XXX) again.
  3. If the same error occurs for a different pacakge, repeat step 2 for the problematic package.

Note: if the steps above don't solve the problem, try executing them in R rather than RStudio.

4.1.6 Compilation failed

ERROR: compilation failed for package 'XXX'
* removing '.../XXX'

If you install packages that require compilation, Rtools must be installed.

  1. Install Rtools (especially if you also get a warning like Rtools is required to build R packages, but is not currently installed). See section 3.1.
  2. Try reinstalling as you did before, e.g. install.packages("XXX"). If that fails, try installing from binary, e.g. install.packages("XXX", type = "binary").

4.1.7 Unsupported URL scheme

Error in utils::download.file(url, path, method = method, quiet = quiet, :
    unsupported URL scheme

This may be accompanied by Warning: unable to access index for repository https://... and/or package 'XXX' is not available (for R version 3.6.1)

This may be a firewall/proxy issue (where CRAN mirror sites are blocked).

  1. Try specifying the repository manually, e.g. install.packages("XXX", dependencies = TRUE, repos = "http://cran.rstudio.com/"). For a more permanent solution, use options(repos = "http://cran.rstudio.com/").
  2. Tools > Global Options > Packages. Uncheck the option "Use Internet Explorer library/proxy for HTTP" and restart R.

4.1.8 Cannot open URL / Unable to access index for repository

4.1.8.1 Github

Downloading GitHub repo ...@master
Error in utils::download.file(url, path, method = method, quiet = quiet, :
    cannot open URL 'https://api.github.com/repos/.../master'

This may happen when trying to install a package from github, e.g.

devtools::install_github(repo)

where repo is the repository address (see ?install_github).

To see if this problem is specific to this package, or github more broadly, try this test:

devtools::install_github("yihui/testit")
  1. The cause may be the default parameter for the argument method (in utils::download.file called from utils::install.packages called from install_github) which is auto, and this translates into wininet on Windows machines. Try changing this to one of the other methods (libcurl, wget, or curl). E.g. devtools::install_github("XXX", method = libcurl)
  2. This could be a TLS issue. GitHub does not support TLS v1.0 or v1.1. Try enabling TLS v1.2 in your internet browser. A guide can be found here: https://knowledge.digicert.com/generalinformation/INFO3299.html. (For Chrome and Safari users, TLS 2.0 should be enabled automatically.)
  3. Try downloading the compressed file from GitHub using the instructions in Section 2.3, then proceed to install from the local source file (see Section 2.2).

Source: https://github.com/r-lib/remotes/issues/130

4.1.8.2 Other sources

unable to access index for repository https://cran.rstudio.com/src/contrib
    cannot open URL 'https://cran.rstudio.com/src/contrib/PACKAGES'

or

trying URL '...'
Error in utils::download.file("https://github.com/repos/...", :
    cannot open URL 'https://github.com/repos/...'

  1. Try specifying the repository using "http" rather than "https", e.g. install.packages("XXX", repos = "http://cran.rstudio.com").
  2. On the RStudio menu, go to Tools > Global Options... > Packages > and uncheck the box "Use secure download method for HTTP". Restart R then try again.

4.1.9 InternetOpenUrl failed

InternetOpenUrl failed: 'An error occurred in the secure channel support'

This suggests a firewall/proxy issue.

  1. If installing, set the repository manually. E.g. install.packages("XXX", repos = "http://cran.rstudio.com/").
  2. If downloading, try changing the download method. E.g. utils::download.file(..., method = "libcurl"), or a more permanent solution: options(download.file.method = "libcurl"). Available methods are: wininet, libcurl, wget, and curl. (This may change the error to HTTP status was '404 Not Found'.)
  3. On the RStudio menu, go to Tools > Global Options... > Packages > and uncheck the box "Use secure download method for HTTP". Restart R then try again.
  4. Further diagnosis pending. Please refer to my unresolved question on Stack Overflow: https://stackoverflow.com/questions/59101045/download-file-error-internetopenurl-failed-an-error-occurred-in-the-secure

4.2 Warnings

4.2.1 'lib' is unspecified

Installing package into '...' (as 'lib' is unspecified)

This means the packages will be installed into the directory shown because you didn't specify it. This is usually fine. If you need to change the library directory, see Section 2.5.

4.2.2 'lib' is not writable

Warning in install.packages :
    'lib = ...' is not writable

When R/RStudio is unable to write to the specified (or default) library path, it usually informs you where the binary source files are located. So R was able to download the source (zipped) files, it just wasn't able to install them. You can try manually installing these packages, but you will probably encounter the same folder permission issue, and this will not solve the root problem.

  1. If possible, try to get local admin access to the default library path (where R is installed).
  2. If that isn't possible or doesn't solve the issue, create a new folder that you do have write permissions for and set this as the new (default) library path. See Section 2.5 for instructions.

The above error message may be succeeded by:

Would you like to use a personal library instead? (yes/No/cancel)

If you select "no" you will see the error: Error in install.packages : unable to install packages. Instead, you shouuld select "yes" and locate your personal library to install the packages to. For a more permanent solution in changing the library path, see Section 2.5.