2.3.1 • Public • Published


    Sync loading routine for a small comma-separated values file (.csv). Returns an array of objects, takes property names from the first line. Assumes everything is a string in quotes.

    Package info

    ci status semantic-release


    Requires nodejs

    npm install -S csv-load-sync


    Example CSV file with two records

    "1","iPhone 4"
    "2","iPhone 4S"

    Example CSV file with three records

    "1","John","Smith","US","2013-08-04 23:57:38"
    "2","Greg","Smith","US","2013-07-12 13:27:18"
    "3","Harold","Smith","GB","2013-07-16 21:17:28"

    Simple example

    const {load} = require('csv-load-sync');
    const csv = load('path/to/file.csv');
    // csv is an Array of objects

    Convert values

    You can convert every value from string to a desired type for the specified columns. For example to convert device IDs to an integer, while make the descriptions all uppercase:

    const {load} = require('csv-load-sync')
    const csv = load('./phone.csv', {
      convert: {
        deviceId: parseInt,
        description: (s) => s.toUpperCase(),
    // objects:
    // deviceId: 1, description: "IPHONE 4"
    // deviceId: 2, description: "IPHONE 4S"

    Useful conversions:

    • to boolean: (s) => (s === 'true' ? true : false)
    • to integer: parseInt
    • to floats: parseFloat

    Custom line splitting

    Sometimes CSV data includes commas naturally, for example the follwing file has GPS location numbers which should be considered together.


    We need to split each record line differently. You can pass the line to columns splitter function when calling load

    function split(line, lineNumber) {
      if (lineNumber === 0) { // title line
        return line.split(',')
      // our line will be <location>,<lat>,<lon>
      // and we want to combine lat and lon
      var parts = line.split(',')
      return [parts[0], parts[1] + ',' + parts[2]];
    var results = load(filename, {
      getColumns: split
      place: 'home',
      location: '-41.20,20.11'
    }, {
      place: 'work',
      location: '-41.3,20.2'


    Blank lines and lines starting with # are skipped.

    Skip columns

    Sometimes you want to skip certain columns. Use an option:

    const results = load(filename, {
      skip: ['lastLogin', 'country'],

    Parse given text

    If you load the CSV text yourself, you can use `` to parse it

    const {parseCSV} = require('csv-load-sync')
    // csv is your text to be parsed
    const records = parseCSV(csv)

    Get columns

    You can just get the header names from the CSV file

    const {getHeaders} = require('csv-load-sync')
    const names = getHeaders('path/to/file.csv')
    // names is an array of strings

    Fine print

    Author: Gleb Bahmutov © 2015

    License: MIT - do anything with the code, but don't blame me if it does not work.

    Spread the word: tweet, star on github, etc.



    npm i csv-load-sync

    DownloadsWeekly Downloads






    Unpacked Size

    8.8 kB

    Total Files


    Last publish


    • bahmutov