readstat-rs

Read, inspect, and convert SAS binary (.sas7bdat) files — from Rust code, the command line, or the browser. Converts to CSV, Parquet, Feather, and NDJSON using Apache Arrow.

The original use case was a command-line tool for converting SAS files, but the project has since expanded into a workspace of crates that can be used as a Rust library, a CLI, or compiled to WebAssembly for browser and JavaScript runtimes.

🔑 Dependencies

The command-line tool is developed in Rust and is only possible due to the following excellent projects:

• The ReadStat C library developed by Evan Miller
• The arrow Rust crate developed by the Apache Arrow community

The ReadStat library is used to parse and read sas7bdat files, and the arrow crate is used to convert the read sas7bdat data into the Arrow memory format. Once in the Arrow memory format, the data can be written to other file formats.

💡 Note: The ReadStat C library supports SAS, SPSS, and Stata file formats. The readstat-sys crate exposes the full ReadStat API — all 125 functions across all formats. However, the higher-level crates (readstat, readstat-cli, readstat-wasm, readstat-tests) currently only implement support for SAS .sas7bdat files.

🚀 CLI Quickstart

Convert the first 50,000 rows of example.sas7bdat (by performing the read in parallel) to the file example.parquet, overwriting the file if it already exists.

readstat data /some/dir/to/example.sas7bdat --output /some/dir/to/example.parquet --format parquet --rows 50000 --overwrite --parallel

📦 CLI Install

Download a Release

[Mostly] static binaries for Linux, macOS, and Windows may be found at the Releases page.

Setup

Move the readstat binary to a known directory and add the binary to the user’s PATH.

Linux & macOS

Ensure the path to readstat is added to the appropriate shell configuration file.

Windows

For Windows users, path configuration may be found within the Environment Variables menu. Executing the following from the command line opens the Environment Variables menu for the current user.

rundll32.exe sysdm.cpl,EditEnvironmentVariables

Alternatively, update the user-level PATH in PowerShell (replace C:\path\to\readstat with the actual directory):

$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$currentPath;C:\path\to\readstat", "User")

After running the above, restart your terminal for the change to take effect.

Run

Run the binary.

readstat --help

⚙️ CLI Usage

The binary is invoked using subcommands:

• metadata → writes file and variable metadata to standard out or JSON
• preview → writes the first N rows of parsed data as csv to standard out
• data → writes parsed data in csv, feather, ndjson, or parquet format to a file

Column metadata — labels, SAS format strings, and storage widths — is preserved in Parquet and Feather output as Arrow field metadata. See docs/TECHNICAL.md for details.

For the full CLI reference — including column selection, parallelism, memory considerations, SQL queries, reader modes, and debug options — see docs/USAGE.md.

For library, API server, and WebAssembly usage, see Examples below.

🛠️ Build from Source

Clone the repository (with submodules), install platform-specific developer tools, and run cargo build. Platform-specific instructions for Linux, macOS, and Windows are in docs/BUILDING.md.

💻 Platform Support

📚 Documentation

🧩 Workspace Crates

For full architectural details, see docs/ARCHITECTURE.md.

💡 Examples

The examples/ directory contains runnable demos showing different ways to use readstat-rs.

To use readstat as a library in your own Rust project, add the readstat crate as a dependency.

🔗 Resources

The following have been incredibly helpful while developing!

• How to not RiiR
• Making a *-sys crate
• Rust Closures in FFI
• Rust FFI: Microsoft Flight Simulator SDK
  • Part 1
  • Part 2
• Stack Overflow answers by Jake Goulding
• ReadStat pull request to add MSVC/Windows support
• jamovi-readstat appveyor.yml file to build ReadStat on Windows
• Arrow documentation for utilizing ArrayBuilders