Guide · Open source

How to use async: install, run tasks and limit concurrency

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Async is an MIT-licensed JavaScript utility module with functions for working with asynchronous code, such as running many tasks over a list of items. This guide covers installing it with npm, and shows the two examples from the project's README: one using Node-style callbacks and one using ES2017 async functions with a concurrency limit. After reading it you will know how to install the package and run a task over a collection, with or without a limit on how many run at once.

asynccaolan/async · ★ 28.1k · MIT Install options & downloads

Quick start

1Check Node.js and npm. Make sure Node.js and npm are installed. The README does not state a minimum Node.js version.
2Install the package. Run npm i async in your project folder.
3Require Async. Add var async = require("async"); to a Node.js file, or import it through your bundler.
4Pick a function. Use forEachOf for objects and mapLimit when you want a limit on concurrent tasks.
5Write the task. Write a task that takes a value and a callback, or an async function that returns a result.
6Handle the final callback. Check err in the final callback, then use the results once all tasks have finished.
7Read the docs. Visit caolan.github.io/async for the full list of functions.

What Async is and who it is for

Async is a utility module that provides functions for working with asynchronous code. It was originally designed for Node.js, and it can also be used directly in the browser.

It suits JavaScript developers who need to run many asynchronous operations over a collection of items, Node.js projects that use callback-style code, and developers who want to limit how many asynchronous tasks run at the same time. It is a code library with no user interface, so it is not aimed at non-programmers.

Running tasks over a list of items
Optional concurrency limits
Usable in Node.js and the browser
An ESM/MJS build for bundlers such as Webpack and Rollup

Install Async with npm

Async is installed with npm, so you need Node.js and npm available. The README does not state a required Node.js version. Run the install command in your project folder.

npm i async

Run a task over an object with forEachOf

The first README example uses Node-style callbacks. The forEachOf function calls your task for each key and value in an object. Each task calls its callback when it finishes, and the final callback runs once all tasks are done or when an error is passed back. The example reads several JSON files and stores the parsed results in one object.

Note that the example uses fs without a require line for it, so add your own require for the file system module when you copy it.

The task receives value, key and callback.
Call callback(err) to stop with an error, or callback() on success.
The final callback receives err and runs after all tasks finish.

var async = require("async");

var obj = {dev: "/dev.json", test: "/test.json", prod: "/prod.json"};
var configs = {};

async.forEachOf(obj, (value, key, callback) => {
    fs.readFile(__dirname + value, "utf8", (err, data) => {
        if (err) return callback(err);
        try {
            configs[key] = JSON.parse(data);
        } catch (e) {
            return callback(e);
        }
        callback();
    });
}, err => {
    if (err) console.error(err.message);
    // configs is now a map of JSON data
    doSomethingWith(configs);
});

Limit concurrency with mapLimit and async functions

The second README example shows ES2017 async functions. The mapLimit function takes a list, a limit, and a task. The number 5 in the example sets how many tasks may run at the same time. The final callback receives the results as an array in the same order as the input.

This is the pattern to use when you want to fetch many URLs without starting all requests at once.

The second argument is the concurrency limit.
The task can be an async function that returns a value.
The final callback gets err and results.

var async = require("async");

// ...or ES2017 async functions
async.mapLimit(urls, 5, async function(url) {
    const response = await fetch(url)
    return response.body
}, (err, results) => {
    if (err) throw err
    // results is now an array of the response bodies
    console.log(results)
})

Use Async in the browser or with bundlers

Async can be used directly in the browser. An ESM/MJS version is included in the main async package and should be picked up automatically by compatible bundlers such as Webpack and Rollup. If you need a pure ESM build, the README points to the separate async-es package.

For the full function reference, the README links to the online documentation at caolan.github.io/async.

What people use it for

Reading several configuration files and collecting them into one object with forEachOf
Fetching a list of URLs while capping the number of simultaneous requests with mapLimit
Running callback-style Node.js code over a collection of items
Using the ESM build in a Webpack or Rollup project

Frequently asked questions

How do I install async?

Run npm i async in your project folder. The package is installed with npm, so you need npm and Node.js available.

Is async free to use?

Yes. Async is released under the MIT licence, as stated in the project's listing.

What do I need to run async?

You need Node.js and npm to install it. The README does not specify a Node.js version, so check the project's package details if you need one.

Can I use async in the browser?

Yes. The README says it can be used directly in the browser, and an ESM/MJS build is included for compatible bundlers such as Webpack and Rollup.

How do I limit how many tasks run at once?

Use mapLimit and pass the maximum number as the second argument, as in the README example that uses 5. The README does not compare this to other libraries.

What are alternatives to async?

The project lists p-limit, p-map, bluebird and async-es as comparable projects. The README does not compare these approaches, so review each one before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Async suits JavaScript developers who run many asynchronous tasks over collections, especially Node.js projects built on callbacks or those that need a concurrency limit. If you only use native Promises and async/await and do not need these helpers, you may not need an extra library, and the README does not compare the two approaches.

Install options & downloads