csv2

CSV parsing for Crystal, at memory speed.

stdlib CSV is slow on real data

The stdlib CSV module is the easy choice, but it does not hold up on large files. Reading a 1.2 GB Kaggle dataset (7.7M rows, 116M cells) with CSV.each_row takes about 20 seconds. Every cell becomes a String through a buffered IO stream, one character at a time.

csv2 is ~5x faster, with the same API

csv2 is a drop-in replacement for the stdlib CSV API. It reads the file through memory mapping and materializes each cell with a single byte-span copy. The same 1.2 GB file parses in about 2.6 seconds:

Same behavior, roughly 5x less waiting on Windows, Linux and macOS. Measured with the stdlib Benchmark.ips module, parsing each file and reading every cell value.

Why you should use it

• Faster: parse gigabyte CSVs in seconds instead of minutes.
• Drop-in: the API matches stdlib CSV, so switching is a one-line change.
• Memory-mapped I/O: the OS hands you the file's bytes directly; no manual reads.
• RFC 4180: quoted fields, embedded commas and newlines, escaped quotes, CRLF, custom separators and quote characters.
• Cross-platform: POSIX and Windows, no runtime dependencies.

How it works for you

require "csv2"    # swap this line for "csv"

CSV2::Reader.each_row(file) do |row|
    puts row   # every cell is a String, like stdlib
end

CSV2::Reader.parse("a,b,c")  # => [["a", "b", "c"]]

reader = CSV2::Reader.new("name,age\nJohn,20", headers: true)
reader.next
reader["name"]   # => "John"
reader.row.to_h  # => {"name" => "John", "age" => "20"}

CSV2::Writer.build { |w| w.row "a", "b" }   # => "a,b\n"

Everything you already do with CSV works the same way — parse, each_row, headers, row access by name or index, building output, but faster.

Install

Add the dependency to your shard.yml:

dependencies:
  csv2:
    github: naqvis/csv2

Then run shards install.

Development

crystal spec

License

MIT

Contributors

• Ali Naqvi — creator and maintainer