# ls

> Cleanly traverse directories in node

Latest version **1.0.0** (published 2026-04-12) · Unlicense license · 0 weekly downloads

## Install

```sh
npm install ls
pnpm add ls
yarn add ls
bun add ls
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2026-04-12 |
| First published | 2013-01-17 |
| Weekly downloads | 0 |
| License | Unlicense |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 1 |
| Unpacked size | 5.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Awnist |
| Maintainers | awnist |

## Links

- npm: https://www.npmjs.com/package/ls
- Repository: https://github.com/awnist/ls
- Homepage: https://github.com/awnist/ls#readme
- Issues: https://github.com/awnist/ls/issues
- npm.io page: https://npm.io/package/ls

## Dependencies (1)

- [glob](https://npm.io/package/glob.md) ^13.0.6

## Recent versions

- 1.0.0 (latest) — 2026-04-12
- 0.2.1 — 2016-08-22
- 0.2.0 — 2016-07-14
- 0.1.0 — 2014-06-04
- 0.0.2 — 2013-02-22
- 0.0.1 — 2013-01-17

## README

## What is "ls"?

`ls` is a node module for cleanly traversing directories and listing files.

The primary goal is a flexible, expressive syntax.

## Installation

```
$ npm i ls
```

## Overview

First require (CommonJS):

```
const ls = require('ls');
```

Or import (ESM):

```
import ls from 'ls';
```

Then you can be as sparse as

```
for (const file of ls('/path/*')) {
  console.log(file.name)
}
```

Or as elaborate as

```
ls(
  '/path/*',
  { recurse: true },
  /jpg/,
  file => console.log(`${file.name} is in ${file.path} and is ${file.stat.size}`)
)
```

## Usage

The only required argument is the initial path, the rest can be omitted.

```
ls([path/s], {config}, /file regex/, iteratorFunction)
```

Each file produces an object with the following parameters:

- full: The path and file (/foo/bar/baz.jpg)
- path: The path to the file (/foo/bar/)
- file: The file (baz.jpg)
- name: The file without an extension (baz)
- stat: A lazy loaded stat object from [fs.Stats](http://nodejs.org/api/fs.html#fs_class_fs_stats)

You can either grab the whole list

```
const all_files = ls('/path/*')
for (const file of all_files) {
  console.log(file.name, 'is', file.stat.size);
}
```

Or use an iterator function, with the context being the file's object

```
const prettysize = require('prettysize');
ls('/tmp/*', file => console.log(`${file.name} is ${prettysize(file.stat.size)}`));
```

The {config} object accepts the following parameters:

- recurse: Should we recurse into directories? (Boolean, default is false)
- type: What kind of files should we return? ('all', 'dir', 'file', default is 'all')

The /regex/ will only return matching files. When `recurse` is enabled, non-matching directories will still be descended into.

The iterator function is mostly a style preference, but can be handy if you need to throw an error and stop traversal.

## License

ls is [UNLICENSED](http://unlicense.org/). Do whatever you want with it.

---
_Source: https://npm.io/package/ls · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._