Diagnosing R Package Installation Failures from Missing System Libraries

R Package Installation Fails Because a System Library Is Missing

You run install.packages("sf") or a similar spatial, XML, or network package and R stops with an error such as configuration failed for package ‘sf’ or gdal-config not found. The useful takeaway is that many R packages wrap C or C++ libraries. R cannot finish the installation until the operating system provides the matching development headers and shared libraries.

Quick Diagnostic Reference

Ordered Troubleshooting Checks

1. Reproduce the failure and capture the full output. Run in the R console: install.packages("sf"). Where to run: R console or RStudio. Permissions: a user account that can write to the selected R library. Expected check: the error text names a missing program, such as gdal-config, xml2-config, or curl-config.
2. Identify the required system dependency. Inspect the package’s SystemRequirements field on CRAN or with packageDescription("sf"). Expected check: a named system library or config script appears.
3. Check whether the required command exists on the system. Run in the shell, not R: which gdal-config, replacing gdal-config with the tool named in the error. Permissions: regular user. Expected check: a filesystem path is printed; no output means the tool is absent.
4. Confirm the R library location. Run in R: .libPaths() and installed.packages()[, c("Package", "LibPath")]. Expected check: the target package is absent or listed under a writable path.
5. Install the operating system package that provides the missing headers. Example for Debian/Ubuntu: sudo apt-get update && sudo apt-get install -y libgdal-dev libgeos-dev libproj-dev. Where to run: system shell. Permissions: root or sudo. Risk: package names differ by distribution and OS version; installing the wrong package does not resolve the error.
6. Reinstall the R package from source. Run in R: install.packages("sf"). Expected check: configuration completes without a missing-tool error and the package installs.

Fixes Tied to Diagnostic Findings

• If configure fails because a config script is missing: install the OS-level development package named in SystemRequirements, then repeat install.packages().
• If the package is missing from installed.packages(): the earlier install did not finish. Return to the first check after installing system dependencies.
• If library() cannot load a shared object: install the matching runtime package, confirm LD_LIBRARY_PATH if a custom path is used, and reload the package.

Concrete Example: Installing the sf Package on Ubuntu

This example assumes Ubuntu 22.04 or later and an R installation that can compile packages from source.

# Run in the system shell
sudo apt-get update
sudo apt-get install -y libgdal-dev libgeos-dev libproj-dev

# Run in the R console
install.packages("sf")
library(sf)
sf_extSoftVersion()

Where to run: system shell for apt-get; R console for install.packages and library. Permissions: sudo or root for apt-get; ordinary user for R if the library directory is writable. Expected check: library(sf) produces no error and sf_extSoftVersion() returns GDAL, GEOS, and PROJ versions. Risk: compilation can take several minutes; an outdated system repository may provide a library version too old for the package.

Limitations

• Older operating system repositories may not carry the library version a recent R package requires. Consider a precompiled binary package or a container image with newer system libraries.
• This guide does not cover failures caused by R version incompatibility, corrupted package archives, or network timeouts from CRAN mirrors.
• Some packages require non-standard environment variables, such as GDAL_CONFIG, that must point to a custom installation.

Practical Way to Check the Result

Start a fresh R session and run:

library(sf)
print(sf_extSoftVersion())

If the package loads and prints version information, the missing system dependency has been resolved. If R reports a missing shared object, revisit the runtime library installation step.

Escalation Criteria

Escalate to a system administrator or package maintainer when:

• The required system package is unavailable in your operating system’s repositories and you cannot install software without root access.
• Installation succeeds but loading the package crashes the R session, which suggests a binary or ABI mismatch rather than a missing header.
• The same error occurs after installing every dependency listed in SystemRequirements.