# Listing the contents of an IPFS directory

When storing data using the default options, Web3.Storage will wrap your uploaded files in an IPFS directory listing. This preserves the original filenames and provides a nicer user experience when downloading files.

The Retrieval guide shows several ways to fetch your data from IPFS using the CID returned by Web3.Storage and the original filenames. However, you may want to simply list the contents of an IPFS directory without downloading all the data inside.

This simple how-to guide will show a few ways to list the contents of an IPFS directory:

# Using the JavaScript ipfs-http-client package

You can use the ipfs-http-client package (opens new window) to send requests to remote IPFS nodes, including public gateway nodes like the one available at https://dweb.link.
The function below uses the HTTP client package to call the ls method, which yields an object describing each link from an IPFS directory object to the files inside.

import { create } from 'ipfs-http-client';

async function getLinks(ipfsPath) {
  const url = 'https://dweb.link/api/v0'
  const ipfs = create({ url })

  const links = []
  for await (const link of ipfs.ls(ipfsPath)) {

See the example output below for the structure of the response objects.

Show getLinks() usage example
    name: 'dr-is-tired.jpg',
    path: 'bafybeifpaez32hlrz5tmr7scndxtjgw3auuloyuyxblynqmjw5saapewmu/dr-is-tired.jpg',
    size: 94482,
    cid: CID(bafkreiabltrd5zm73pvi7plq25pef3hm7jxhbi3kv4hapegrkfpkqtkbme),
    type: 'file'
    name: 'not-distributed.jpg',
    path: 'bafybeifpaez32hlrz5tmr7scndxtjgw3auuloyuyxblynqmjw5saapewmu/not-distributed.jpg',
    size: 414201,
    cid: CID(bafkreidrsgkip425zjamc3pvmil7dpatss7ncedyaatepxyionxi7py5fq),
    type: 'file'
    name: 'youareanonsense.jpg',
    path: 'bafybeifpaez32hlrz5tmr7scndxtjgw3auuloyuyxblynqmjw5saapewmu/youareanonsense.jpg',
    size: 55415,
    cid: CID(bafkreiaqv66m5nd6mwgkk7h5lwqnjzj54s4f7knmnrjhb7ylzqfg2vdo54),
    type: 'file'

# Using HTTP requests

You can use any HTTP client to invoke the ls API call (opens new window) on a remote IPFS node, including public gateway nodes like the one at https://dweb.link.

To get the contents of a directory using the HTTP API, make a GET request using a URL of the form:


Replace <gateway-host> with the address of an IPFS HTTP gateway, and replace <cid> with the Content Identifier of the directory you want to list.

For the examples, we'll use the URL https://dweb.link/api/v0/ls?arg=bafybeifpaez32hlrz5tmr7scndxtjgw3auuloyuyxblynqmjw5saapewmu.

    # Using the IPFS command line

    If you have the IPFS command line interface (opens new window) installed, you can use the ipfs ls command (opens new window) to list the contents of a directory.

    ipfs ls -v bafybeifpaez32hlrz5tmr7scndxtjgw3auuloyuyxblynqmjw5saapewmu
    Hash                                                        Size   Name
    bafkreiabltrd5zm73pvi7plq25pef3hm7jxhbi3kv4hapegrkfpkqtkbme 94482  dr-is-tired.jpg
    bafkreidrsgkip425zjamc3pvmil7dpatss7ncedyaatepxyionxi7py5fq 414201 not-distributed.jpg
    bafkreiaqv66m5nd6mwgkk7h5lwqnjzj54s4f7knmnrjhb7ylzqfg2vdo54 55415  youareanonsense.jpg

    Note that omitting the -v flag will remove the header line from the output. Run ipfs ls --help for more usage information.