readxl

Core Capabilities

• No external dependencies: Does not require Java or Perl, making it easy to install across operating systems.
• Encoding: Automatically re-encodes non-ASCII characters to UTF-8.
• Date/Time Support: Correctly loads datetimes into POSIXct columns, supporting both Windows (1900) and Mac (1904) date specifications.
• Automatic Discovery: By default, it discovers the minimal data rectangle. You can override this using range, skip, or n_max.
• Type Inference: Column names and types are determined from the data by default, but can be manually specified via col_names and col_types.
• Output Format: Returns a tibble for improved printing and data manipulation.

The readxl package is the Tidyverse solution for reading both legacy .xls (Excel '97-2007) and modern .xlsx (XML-based) formats.

Key advantages include:

• Consistency: It follows Tidyverse ingest conventions (similar to readr and haven), making it easy to transition to downstream tools like tibble, tidyr, dplyr, purrr, and ggplot2.
• No External Dependencies: Unlike packages like xlsx or XLConnect which require Java (Apache POI), or gdata which requires Perl, readxl embeds its parsing libraries (libxls for .xls and RapidXML for .xlsx). This makes it easier to install and use across Mac, Windows, and Linux without managing complex external environments.
• Data Format: Once imported, data is stored as a tibble, a specialized version of a data frame optimized for tidyverse workflows.

If you prefer a GUI over writing code, RStudio provides an import helper for readxl that allows you to preview data and automatically generate the necessary read_excel() code.

How to access the helper:

1. Environment Pane: Click Import Dataset > From Excel...
2. Files Pane: Click on a .xls or .xlsx file > Import Dataset...

Features of the RStudio helper:

• Argument Exposure: Easily set important arguments like skip, n_max, or range via a user interface.
• Data Preview: See how your settings (especially column typing) affect the resulting data before importing.
• Code Generation: Use the 'Code Preview' to see the exact read_excel() call required, or use the clipboard feature to copy it into your script.
• Note: The IDE helper currently has better support for importing files directly from a URL than the readxl package itself.

You can install readxl from CRAN via the standard install.packages() method. If you are using the tidyverse suite, you can install the entire collection, but note that readxl must still be loaded explicitly using library(readxl) as it is not part of the core tidyverse package loaded by library(tidyverse).

To install the development version from GitHub, use the pak package.

# Install from CRAN
install.packages("readxl")

# Or install the whole tidyverse
install.packages("tidyverse")

# Install development version from GitHub
# install.packages("pak")
pak::pak("tidyverse/readxl")

When calling read_excel(), you can use the sheet argument to target a specific worksheet. You can provide either the exact string name of the sheet or its integer position (index).

# By name
read_excel(xlsx_example, sheet = "chickwts")

# By index
read_excel(xls_example, sheet = 3)

The package includes several example files for testing and documentation. Use readxl_example() to interact with them:

• readxl_example(): Lists all available example filenames.
• readxl_example("filename"): Returns the full file path to the specified example file.

# List examples
readxl_example()

# Get path to a specific example
path <- readxl_example("clippy.xls")

The primary function read_excel() reads both legacy .xls and modern .xlsx files, automatically detecting the format from the file extension. It returns data as a tibble.

library(readxl)

# Basic usage
data <- read_excel("path/to/your_file.xlsx")

Use excel_sheets() to retrieve a character vector of all worksheet names within an Excel file.

# Get sheet names
sheets <- excel_sheets("path/to/your_file.xlsx")

You can restrict the data imported by using range, n_max, or skip.

• n_max: Limits the number of rows read.
• range: Accepts Excel-style cell ranges (e.g., `