package-dependencies

name	Package Dependencies
description	Complete guide to managing R package dependencies, including Imports vs Suggests, namespace imports, and handling dependencies in code, tests, examples, and vignettes

Package Dependencies

Overview

Managing dependencies correctly is critical for R packages. This skill covers the different dependency types, how to declare and use them, and common patterns for conditional dependencies.

CRITICAL Concept: Listing vs Importing

Most important rule: Listing a package in Imports: does NOT make its functions available!

# DESCRIPTION:
Imports:
  dplyr

# This does NOT work:
my_function <- function(data) {
  filter(data, value > 0)  # ERROR: object 'filter' not found
}

# You must ALSO either:

# Option 1: Use explicit namespace (RECOMMENDED for most cases):
my_function <- function(data) {
  dplyr::filter(data, value > 0)
}

# Option 2: Import to namespace via roxygen2:
#' @importFrom dplyr filter
my_function <- function(data) {
  filter(data, value > 0)
}

Listing in DESCRIPTION ensures the package is installed. Importing to NAMESPACE makes functions available in your code.

Dependency Types

Imports

Packages required for your package to work.

# DESCRIPTION:
Imports:
    dplyr (>= 1.0.0),
    rlang (>= 1.0.0),
    tidyr

Guarantees:

• Installed when your package is installed
• Loaded when your package is loaded (but not attached)
• Functions available via pkg::fun()

Use for:

• Packages your code depends on
• Packages used in most functions
• Critical dependencies

Usage pattern:

# Default: Use pkg::fun()
my_function <- function(x) {
  dplyr::mutate(x, new_col = value * 2)
}

# Or import specific functions:
#' @importFrom dplyr mutate select filter
my_function <- function(x) {
  x %>%
    filter(value > 0) %>%
    mutate(doubled = value * 2)
}

Suggests

Optional packages for enhanced functionality, tests, or documentation.

# DESCRIPTION:
Suggests:
    ggplot2,
    testthat (>= 3.0.0),
    knitr,
    rmarkdown,
    covr

No guarantees:

• May or may not be installed
• Must check availability before use
• Cannot use pkg::fun() without checking

Use for:

• Packages for optional features
• Testing frameworks (testthat, covr)
• Vignette builders (knitr, rmarkdown)
• Packages for examples only
• Heavy dependencies users may not need

Usage pattern:

# MUST check availability:
my_plot <- function(data) {
  if (!requireNamespace("ggplot2", quietly = TRUE)) {
    stop("Package 'ggplot2' required but not installed.\n",
         "Install with: install.packages('ggplot2')",
         call. = FALSE)
  }

  ggplot2::ggplot(data, ggplot2::aes(x, y)) +
    ggplot2::geom_point()
}

# Better: Use rlang::check_installed()
my_plot <- function(data) {
  rlang::check_installed("ggplot2", reason = "to create plots")

  ggplot2::ggplot(data, ggplot2::aes(x, y)) +
    ggplot2::geom_point()
}

Depends

Makes another package's functions available in user's workspace (rarely recommended).

# DESCRIPTION:
Depends:
    R (>= 4.1.0),
    methods

Effects:

• Package is attached when yours is attached
• Functions available in user's search path
• Modifies user's environment

Modern usage:

• R (>= version) - minimum R version (ALWAYS use this)
• methods - if defining S4 classes
• Almost never use for other packages

Why avoid:

# If you use Depends: dplyr:
library(mypackage)  # Also attaches dplyr

# Now user's environment has all dplyr functions:
filter  # Available (might conflict with stats::filter)

Better approach:

# Use Imports + explicit namespace:
Imports: dplyr

# In code:
dplyr::filter(...)

LinkingTo

For packages with C/C++ code using headers from other packages.

# DESCRIPTION:
LinkingTo:
    Rcpp,
    RcppArmadillo

Use for:

• Rcpp packages
• Packages providing C++ headers
• Compiled code dependencies

Often combined with Imports:

Imports:
    Rcpp (>= 1.0.0)
LinkingTo:
    Rcpp

Config/Needs/*

Dependencies for development tools, not package functionality.

# DESCRIPTION:
Config/Needs/website:
    pkgdown
Config/Needs/coverage:
    covr
Config/Needs/development:
    devtools,
    usethis,
    roxygen2

Use for:

• pkgdown for website
• covr for coverage
• Development tools
• CI-specific packages

Not installed by default:

# Install with:
pak::pak("mypackage", dependencies = TRUE)  # Includes Config/Needs/*

Adding Dependencies

Using usethis Helpers

# Add to Imports:
usethis::use_package("dplyr")
usethis::use_package("rlang", min_version = "1.0.0")

# Add to Suggests:
usethis::use_package("ggplot2", type = "Suggests")

# Add to Imports with @importFrom:
usethis::use_import_from("dplyr", c("filter", "mutate", "select"))
# Adds to DESCRIPTION AND creates roxygen2 skeleton

# Add minimum R version:
usethis::use_package("R", min_version = "4.1.0", type = "Depends")

Manual Addition

# DESCRIPTION:
Imports:
    dplyr (>= 1.1.0),
    rlang (>= 1.0.0),
    tidyr,
    purrr
Suggests:
    ggplot2 (>= 3.4.0),
    testthat (>= 3.0.0)

Version specifications:

dplyr                    # Any version
dplyr (>= 1.0.0)        # At least 1.0.0
dplyr (>= 1.0.0, < 2.0.0)  # Rarely used, not recommended

Importing Functions to Namespace

Pattern 1: Explicit Namespace (Recommended)

# No NAMESPACE imports needed
# Just use pkg::fun() everywhere:

my_function <- function(data) {
  data %>%
    dplyr::filter(value > 0) %>%
    dplyr::mutate(doubled = value * 2) %>%
    dplyr::select(id, doubled)
}

Advantages:

• Clear where functions come from
• No NAMESPACE management needed
• Easy to understand
• No import conflicts

Disadvantages:

• More typing
• Slightly verbose

Pattern 2: Selective Import (@importFrom)

# Import specific functions:
#' @importFrom dplyr filter mutate select
#' @importFrom rlang .data .env
my_function <- function(data) {
  data %>%
    filter(value > 0) %>%
    mutate(doubled = .data$value * 2) %>%
    select(id, doubled)
}

When to use:

• Functions used many times
• Infix operators (%>%, %||%, :=)
• Core package dependencies
• Reduces verbosity

Where to put @importFrom:

# Option 1: In function documentation:
#' My function
#' @importFrom dplyr filter mutate
my_function <- function() { ... }

# Option 2: In package-level doc (R/mypackage-package.R):
#' @importFrom dplyr filter mutate select arrange
#' @importFrom rlang .data .env %||%
"_PACKAGE"

# Option 3: Dedicated imports file (R/aaa-imports.R):
#' @importFrom dplyr filter mutate select
#' @importFrom rlang .data %||%
NULL

Pattern 3: Full Import (@import) - Rare

#' @import rlang

Only for:

• rlang (if building tidy evaluation package)
• Your own internal package

Avoid for most packages:

• Namespace pollution
• Potential conflicts
• Unclear provenance

Operators and Infix Functions

Always import operators:

# WRONG - doesn't work:
data %>% dplyr::filter(x > 0)  # Error: %>% not found

# RIGHT:
#' @importFrom magrittr %>%
data %>% dplyr::filter(x > 0)

# Or use base pipe (R >= 4.1):
data |> dplyr::filter(x > 0)  # No import needed

Common operators to import:

#' @importFrom magrittr %>%
#' @importFrom rlang %||% !! !!!
#' @importFrom data.table := .N .SD

Using Dependencies in Different Contexts

In Package Code (R/)

# Imports dependencies - use pkg::fun() or @importFrom:
#' @importFrom dplyr filter
my_function <- function(data) {
  filter(data, value > 0)  # OK: imported
}

# Or:
my_function <- function(data) {
  dplyr::filter(data, value > 0)  # OK: explicit namespace
}

# Suggests dependencies - MUST check first:
my_optional_feature <- function(data) {
  rlang::check_installed("ggplot2", reason = "for plotting")
  ggplot2::ggplot(data, ggplot2::aes(x, y)) +
    ggplot2::geom_point()
}

In Examples (@examples)

# Imports - can use freely:
#' @examples
#' my_function(mtcars)


# Suggests - must check or wrap:
#' @examples
#' \dontrun{
#' # Requires ggplot2
#' my_plot(mtcars)
#' }
#'

#' @examplesIf requireNamespace("ggplot2", quietly = TRUE)
#' my_plot(mtcars)

In Tests (tests/testthat/)

# Imports - can use freely:
test_that("function works", {
  result <- my_function(data)
  expect_equal(result$value, expected)
})

# Suggests - MUST skip if not available:
test_that("plotting works", {
  skip_if_not_installed("ggplot2")

  plot <- my_plot(data)
  expect_s3_class(plot, "gg")
})

test_that("integration with optional package", {
  skip_if_not_installed("dplyr")

  library(dplyr)
  result <- data %>%
    my_transform() %>%
    summarize(mean = mean(value))

  expect_equal(result$mean, 5)
})

In Vignettes (vignettes/)

# YAML header for Suggests dependency:
# ---
# title: "My Vignette"
# vignette: >
#   %\VignetteIndexEntry{My Vignette}
#   %\VignetteEngine{knitr::rmarkdown}
# ---

# First chunk - setup with conditional evaluation:
# ```{r setup, include=FALSE}
# knitr::opts_chunk$set(
#   eval = requireNamespace("ggplot2", quietly = TRUE)
# )
# ```

# Now code chunks only run if ggplot2 available:
# ```{r}
# library(ggplot2)
# ggplot(data, aes(x, y)) + geom_point()
# ```

Alternative: Use separate vignettes:

# DESCRIPTION:
Suggests:
    knitr,
    rmarkdown,
    ggplot2

# vignettes/basic-usage.Rmd - no optional deps
# vignettes/advanced-plotting.Rmd - requires ggplot2

In Documentation (roxygen2)

# References to Suggests packages:
#' @description
#' This function provides plotting capabilities. Requires the
#' \pkg{ggplot2} package to be installed.
#'
#' @seealso [ggplot2::ggplot()] for more plotting options

Minimum Version Specifications

When to Specify Versions

# Always specify if you need specific features: