224

remotes

R Package Installation from Remote Repositories, Including 'GitHub'

Download and install R packages stored in 'GitHub', 'GitLab', 'Bitbucket', 'Bioconductor', or plain 'subversion' or 'git' repositories. This package provides the 'install_*' functions in 'devtools'. Indeed most of the code was copied over from 'devtools'.

repositories

Project Status: Active - The project has reached a stable, usable state and is being actively developed. Linux Build Status Windows Build status CRAN RStudio mirror downloads Coverage Status

Download and install R packages stored in GitHub, BitBucket, or plain subversion or git repositories. This package is a lightweight replacement of the install_* functions in devtools. Indeed most of the code was copied over from devtools.

Features

  • Installers:
    • Install packages with their dependencies.
    • Install from GitHub, GitLab, BitBucket.
    • Install from git and subversion repositories.
    • Install from local files or URLs.
    • Install the dependencies of a local package tree.
    • Install specific package versions from CRAN.
  • Supports Bioconductor packages.
  • Supports the Remotes field in DESCRIPTION. See more here.
  • Supports the Additional_repositories field in DESCRIPTION.
  • Can install itself from GitHub (see below).
  • Does not depend on other R packages.
  • Does not contain compiled code, so no compiler is needed.
  • Does not need any external software (for most of the functionality at least).

Installation

Install the released version of remotes from CRAN:

install.packages("remotes")

You can also install remotes from GitHub. If you already have a previous version of remotes installed, you can use that to install the development version:

remotes::install_github("r-lib/remotes")

Alternatively, you can also call the supplied install-github.R file directly, from within R:

source("https://raw.githubusercontent.com/r-lib/remotes/master/install-github.R")$value("r-lib/remotes")

The https://install-github.me service is also based on remotes. You can use it to install any R package from GitHub via sourcing a URL. E.g. to install remotes itself:

source("https://install-github.me/r-lib/remotes")

Usage

Note that most of the examples here use GitHub. See below for other supported repository types.

To install the latest version of a package in the master branch from GitHub, you can use the user/repo form. Note that user can also be an organization:

remotes::install_github("r-lib/conflicted")

If the R package is inside a subdirectory of the root directory, then give this subdirectory as well:

remotes::install_github("dmlc/xgboost/R-package")

To install a certain branch or commit or tag, append it to the repo name, after an @:

remotes::install_github("gaborcsardi/[email protected]")

To install the latest release, append @*release to the repo name:

remotes::install_github("gaborcsardi/[email protected]*release")

To install a pull request, append # and the id (an integer number) of the pull request to the repo name:

remotes::install_github("r-lib/pkgconfig#7")

Dependencies

Dependencies are automatically installed from CRAN. By default, outdated dependencies are automatically upgraded. In interactive sessions you can select a subset of the dependencies to upgrade.

Dependencies on GitHub

It is also possible to install dependencies from GitHub or other supported repositories. For this you need to add a Remotes field to the DESCRIPTION file. Its format is:

Remotes: [remote::]repo_spec, [remote::]repo_spec, ...

where repo_spec is any repository specification the corresponding install_() function can handle. If remote:: is missing, github:: is assumed. Other possible values: gitlab::,bitbucket::, git::, local::, svn::, url::, version::, cran::, bioc::.

See more about the Remotes field in this vignette.

Additional repositories

remotes supports the Additional_repositories field in DESCRIPTION. This is a way to specify dependencies from non-CRAN package repositories. See the Writing R extensions manual for details.

Bioconductor packages

Bioconductor packages are automatically detected and their dependencies are installed from Bioconductor.

Currently supported remote types

  • GitHub repositories via install_github.
  • Bitbucket repositories via install_bitbucket.
  • Generic git repositories via install_git. They need either a system git installation, or the git2r R package.
  • Local directories or package archive files via install_local.
  • Remote package archive files via install_url.
  • Packages in subversion repositories via install_svn. They need a system subversion installation.
  • Specific package versions from CRAN or other CRAN-like repositories via install_version. This includes outdated and archived packages as well.
  • All dependencies of a package in a local directory via install_deps.

Download methods

  • For R older than 3.2, the curl package is required as remotes falls back to curl::curl_download in that case
  • For R newer than 3.3, default download.file() method is used. (method = "auto")
  • For in between versions,
    • method = "wininet" is used on windows OS
    • method = "libcurl" is used on other OS, if available.

See help("download.file") for informations on these methods and for setting proxies if needed.

Standalone mode

remotes will use the curl, git2r and pkgbuild packages if they are installed to provide faster implementations for some aspects of the install process. However if you are using remotes to install or update these packages (or their reverse dependencies) using them during installation may fail (particularly on Windows).

If you set the environment variable R_REMOTES_STANDALONE=true (e.g. in R Sys.setenv(R_REMOTES_STANDALONE="true")) you can force remotes to operate in standalone mode and use only its internal R implementations. This will allow successful installation of these packages.

Options

remotes uses the following standard R options, see ?options for their details:

  • download.file.method for the default download method. See ?download.file.

  • pkgType for the package type (source or binary, see manual) to install, download or look up dependencies for.

  • repos for the locations of the user's standard CRAN(-like) repositoies.

It also uses some remotes specific options:

  • BioC_git for the URL of the default Bioconductor git mirror.

  • unzip for the path of the external unzip program.

Environment variables

  • The BITBUCKET_USER and BITBUCKET_PASSWORD enrironment variables are used for the default BitBucket user name and password, in install_bitbucket()

  • The GITHUB_PAT environment variable is used as the default GitHub personal access token for all GitHub API queries.

  • The R_REMOTES_UPGRADE environment variable can be used to set a default preferred value for the upgrade = argument accepted by the various install_*() functions. For example, you can set R_REMOTES_UPGRADE=always to upgrade dependent packages without asking the user.

  • Setting R_REMOTES_STANDALONE=true forces remotes to work in standalone mode and avoid loading its optional dependencies (curl, git2 and pkgbuild currently. See "Standalone mode" above.

  • Setting R_REMOTES_NO_ERRORS_FROM_WARNINGS=true avoids stopping the installation for warning messages. Warnings usually mean installation errors, so by default remotes stops for a warning. However, sometimes other warnings might happen, that could be ignored by setting this environment variable.

  • Setting _R_CHECK_FORCE_SUGGESTS_=false while R_REMOTES_NO_ERRORS_FROM_WARNINGS is unset will also avoid stopping the installation for error messages. This is done because a warning is generated during installation when not all Suggested packages are not available.

License

GPL (>= 2) © Mango Solutions, RStudio

News

remotes 2.0.4

remotes (development version)

  • update.package_dependencies() now uses the pkg_type for the cran remote rather than a global type attribute, fixing errors when this global attribute is lost (#291, #304).

  • Credentials are no longer passed to dependencies, as this breaks dependencies which use different credentials or hosts. If you have relied on this behavior a more robust way to provide the credentials is using the appropriate environment variables, e.g. GITHUB_PAT, BITBUCKET_USER etc. (@antoine-sachet, #345).

  • The hash of bitbucket hosts is now correctly retrieved (@antoine-sachet, #344)

  • Fix parsing of Additional_Repositories which have a leading newline (@tmelliott, #251).

remotes 2.0.3

  • The order of choices for upgrade = "ask" now puts the stable ones 'All', 'CRAN only', 'none' first, so they always have the same numbers (#287).

  • update_submodules() now works with empty .gitmodules files (@jsilve24, #329).

  • remotes now understands the "standard" remote type, as produced by packages installed from CRAN using pak (#309)

  • Fix return type of install_remote() when there is a circular dependency (#225)

  • remote_package_name.github_remote() now works properly on Windows (#248)

  • install_bioc() repositories now updated for the Bioconductor 3.8 release. (#239)

  • install_* functions now set the R_LIBS* environment variables for child processes correctly on Windows (@HenrikBengtsson, #253)

  • install_* functions now support the R_REMOTES_UPGRADE environment variable, to set the default for the upgrade argument. See README for details (@kevinushey, #240).

  • install_* functions perform basic HTTP authentication using HTTP headers now. This fixes an issue with install_bitbucket() and private repos (#255).

  • install_* functions now respect the download.file.method option, if download_file() is used for HTTP.

  • install_* functions now use the libcurl method, if the download.file.method option is not set to a different one, and libcurl is available. Before, the wininet method was preferred on Windows. If you rely on the proxy configuration of wininet, then you might want to set the download.file.method option, or use another way to set up proxies, see ?download.file.

  • Remotes without package names are now unconditionally installed (#246).

  • install_github() now includes a more informative error message when the status code is 404, asking the user to check that they have spelled the repo owner and repo correctly (included in the error message), and that they have the required permissions to access the repository.

  • install_* fuctions (via the underlying private install function) now set RGL_USE_NULL="TRUE" in order to avoid errors when running headless and installing any package using rgl (@jefferis, ##333)

remotes 2.0.2

  • install_deps() now installs un-installed remotes packages even when upgrade = "never" (@ankane, #227)

  • install_version() now removes metadata added as a byproduct of using install_url() internally() (#224)

  • install() now avoids converting warnings to errors if R_REMOTES_NO_ERRORS_FROM_WARNINGS is unset and _R_CHECK_FORCE_SUGGESTS_=false. This avoids failures due to Suggested packages potentially being missing.

  • install_bitbucket() now works properly with packages in subdirectories (#220)

  • install_deps() now installs un-installed packages even when upgrade = "never" (#218)

remotes 2.0.1

  • install_github() now bundles a GitHub PAT which is used on Travis to avoid hitting the rate limit too frequently. It also contains a more informative error message when the rate limit is hit on how to setup a GitHub personal access token.

  • The dialog when upgrade = "ask" now has a 'CRAN only' option, to update only CRAN packages.

  • No longer include project specific .Rprofile code in the temporary .Rprofile when R_REMOTES_NO_ERRORS_FROM_WARNINGS=false (the default).

  • update.package_deps() no longer prompts to install uninstalled dependencies, they are always installed (#203).

  • available_packages(), available_packages_set() and available_packges_reset() added to allow caching of the available.packages() database.

remotes 2.0.0

Breaking changes

  • install_github()'s previously deprecated username argument has been removed. (#142)

  • install_deps()'s threads argument has been removed, use the Ncpus argument instead (#153, #154)

  • install_git()'s branch argument has been renamed to ref and branch has been deprecated.

New features

  • remotes now builds packages by default before installing them. This step uses the pkgbuild package, if avilable. If not, it calls R CMD build directly.

  • New install_dev() to install the development version of a CRAN package, based on the URL and BugReports fields in the DESCRIPTION file (#144).

  • install_()* functions now temporally put Rtools on the PATH when necessary, as long as the pkgbuild package is installed.

  • remotes can be forced to use only its internal code by setting the environment variable R_REMOTES_STANDALONE = "true". This is useful when installing optional dependencies of remotes on Windows, such as curl or git2r (#147)

  • When installing, remotes now errors on warnings, to catch cases where packages are only partially installed. This often happens on windows when the package dll is opened in another R process (#113).

  • install_() functions now pass arguments, including authentication information and upgrade down to dependencies (#53, #86, #87).

  • install_() functions allow the seclection of a subset of packages to upgrade, in interactive mode, when upgrade = "ask".

  • install_git() now supports passing credentials, when it is used with git = "git2r" (#106)

  • install_() functions now return the name of the package(s) which were installed (#55).

  • git submodules are now installed if they exist and a git client is available (#138, #133, #103, #82).

  • New install_gitlab() and install_bioc() functions, to install gitlab and bioc remote types.

  • remotes now uses the same SHA updating logic for remotes as devtools, including checking if the SHA of the remote has changed since the last istallation. (#135)

  • install_url() can now install package binaries on windows (r-lib/devtools#1765)

Minor improvements and fixes

  • install_deps() et al. now do not rewrite the type argument from both to binary to allow falling back to source. This fixes various installation failures.

  • remotes now looks up GitHub package names locally, if possible, and uses the GitHub REST API (if the curl package is available, and not in standalone mode). This makes the remote lookup about 10x faster when the remote package has not changed since the last install.

  • Using a GITHUB_PAT no longer prints diagnostic messages by default (r-lib/devtools#1752).

  • remotes now always uses https URLs for R versions that support them (@ankane, #139)

  • Do not include the BioCextra repository in versions after it was deprecated (R 3.5+, Bioc 3.6+).

  • install_() functions now download tarballs (.tar.gz) files rather than zip archives (.zip). This results in generally smaller files and avoids issues with script permissions being lost and strange behavior of some external unzip programs on Windows (#96).

  • Dependency parsing is now more robust to whitespace around the dependency specifications (#73).

  • standardise_dep() exported, for use in devtools.

  • install_local() now defaults to the current directory.

  • install_bitbucket() now correctly supports authentication, and the subdir argument.

  • install_() functions give a helpful warning when the package has long path names, on Windows. In this case building the package usually fails. (#84, #178).

  • install_() functions have now a more robust way of handling various tar programs on Windows (#172).

  • install_() functions now give a helpful warning on older R versions, on Windows, if R.home() contains a space character. Installation usually fails in this case.

  • GitHub API errors now give better error messages, including data about the API rate limits.

remotes 1.1.1

  • Accept HTTPS, SSH, or various browser URLs in GitHub repo specification, @jennybc, #90, #109, #112

remotes 1.1.0

  • URL encode GitHub references, to allow installing from non-alphanumeric branch or tags, @krlmlr #38

  • Better cooperation with proxy servers, and better download method selection on Windows, @cderv, #45, #46

  • install_deps() supports tar balls, #47

  • Allow training slash in GitHub repo specification, #54

  • Work around on some Linux systems, where unzip is set to the empty string, @HenrikBengtsson, #57

  • Check for circular dependencies while installing, #31

  • Updated BioConductor repo URLs for newer BioC versions

remotes 1.0.0

First public release.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.
install.packages("remotes")

2.3.0 by Jim Hester, 19 days ago

https://remotes.r-lib.org, https://github.com/r-lib/remotes#readme

Report a bug at https://github.com/r-lib/remotes/issues

Browse source code at https://github.com/cran/remotes

Authors: Jim Hester [aut, cre] , Gábor Csárdi [aut] , Hadley Wickham [aut] , Winston Chang [aut] , RStudio [cph] , Martin Morgan [aut] , Dan Tenenbaum [aut] , Mango Solutions [cph]

Documentation:   PDF Manual  

GPL (>= 2) license

Imports methods, stats, tools, utils

Suggests brew, callr, codetools, curl, covr, git2r, knitr, mockery, pkgbuild, pingr, rmarkdown, rprojroot, testthat, webfakes, withr

System requirements: Subversion for install_svn, git for install_git

Imported by Orcs, RInno, Require, addinslist, automagic, babette, batata, beastier, codemetar, cyclocomp, devtools, dynutils, golem, jetpack, kim, librarian, natmanager, opencpu, outsider, packager, pacman, pkglite.

Suggested by BiocManager, CNVScope, GSODR, LoopDetectR, MIMSunit, RxODE, UKgrid, USgrid, alfr, codalm, coronavirus, covid19italy, dipsaus, inlmisc, modeltime.ensemble, modeltime.resample, nCov2019, occCite, pct, pxweb, rcompendium, rdwd, renv, sapfluxnetr, swag, tidyfast, tidyvpc, tinyProject, ufs, worcs, xfun.

See at CRAN

R links

R homepage

Download R

Mailing lists

R documentation

R manuals

R FAQs

The R Journal

CRAN links

CRAN homepage

CRAN repository policy

Submit a package

METACRAN stuff

About METACRAN

At github

Report a bug