---
modificationDate: March 20, 2026
title: FileSystem (next)
description: A library that provides access to the local file system on the device.
sourceCodeUrl: 'https://github.com/expo/expo/tree/sdk-53/packages/expo-file-system/src/next'
packageName: 'expo-file-system'
iconUrl: '/static/images/packages/expo-file-system.png'
platforms: ['android', 'ios', 'tvos']
---

<AgentInstructions>

## Submitting Feedback

If this page contains errors, outdated information, or gaps that blocked you from completing a task, report it so the docs can be improved:

curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/versions/v53.0.0/sdk/filesystem-next/","feedback":"🤖 Agent feedback: <specific, actionable description>"}'

Only submit when you have something specific and actionable to report.

</AgentInstructions>

# Expo FileSystem (next)

A library that provides access to the local file system on the device.
Android, iOS, tvOS

> For the complete documentation index, see [llms.txt](/llms.txt). Use this file to discover all available pages.

> The `next` version of the FileSystem API is included in the `expo-file-system` library. It can be used alongside the previous API, and offers a simplified, object oriented way of performing filesystem operations.

> To provide quicker updates, `expo-file-system/next` is currently unsupported in Expo Go and Snack. To use it, create a [development build](/develop/development-builds/create-a-build).

`expo-file-system/next` provides access to the file system stored locally on the device. It can also download files from the network.

## Installation

```sh
npx expo install expo-file-system
```

If you are installing this in an [existing React Native app](/bare/overview), make sure to [install `expo`](/bare/installing-expo-modules) in your project.

## Usage

### Writing and reading text files

```ts
import { File, Paths } from 'expo-file-system/next';

try {
  const file = new File(Paths.cache, 'example.txt');
  file.create(); // can throw an error if the file already exists or no permission to create it
  file.write('Hello, world!');
  console.log(file.text()); // Hello, world!
} catch (error) {
  console.error(error);
}
```

### Downloading files

Using `downloadFileAsync`:

```ts
import { Directory, File, Paths } from 'expo-file-system/next';

const url = 'https://pdfobject.com/pdf/sample.pdf';
const destination = new Directory(Paths.cache, 'pdfs');
try {
  destination.create();
  const output = await File.downloadFileAsync(url, destination);
  console.log(output.exists); // true
  console.log(output.uri); // path to the downloaded file, e.g. '${cacheDirectory}/pdfs/sample.pdf'
} catch (error) {
  console.error(error);
}
```

Or using `expo/fetch`:

```ts
import { fetch } from 'expo/fetch';
import { File, Paths } from 'expo-file-system/next';

const url = 'https://pdfobject.com/pdf/sample.pdf';
const response = await fetch(url);
const src = new File(Paths.cache, 'file.pdf');
src.write(await response.bytes());
```

### Uploading files using `expo/fetch`

You can upload files as blobs directly with `fetch` built into the Expo package:

```ts
import { fetch } from 'expo/fetch';
import { File, Paths } from 'expo-file-system';

const file = new File(Paths.cache, 'file.txt');
file.write('Hello, world!');

const response = await fetch('https://example.com', {
  method: 'POST',
  body: file,
});
```

Or using the `FormData` constructor:

```ts
import { fetch } from 'expo/fetch';
import { File, Paths } from 'expo-file-system/next';

const src = new File(Paths.cache, 'file.txt');
file.write('Hello, world!');

const formData = new FormData();
formData.append('data', file);

const response = await fetch('https://example.com', {
  method: 'POST',
  body: formData,
});
```

### Moving and copying files

```ts
import { Directory, File, Paths } from 'expo-file-system/next';

try {
  const file = new File(Paths.document, 'example.txt');
  file.create();
  console.log(file.uri); // '${documentDirectory}/example.txt'
  const copiedFile = new File(Paths.cache, 'example-copy.txt');
  file.copy(copiedFile);
  console.log(copiedFile.uri); // '${cacheDirectory}/example-copy.txt'
  file.move(Paths.cache);
  console.log(file.uri); // '${cacheDirectory}/example.txt'
  file.move(new Directory(Paths.cache, 'newFolder'));
  console.log(file.uri); // '${cacheDirectory}/newFolder/example.txt'
} catch (error) {
  console.error(error);
}
```

### Using legacy FileSystem API

```ts
import * as FileSystem from 'expo-file-system';
import { File, Paths } from 'expo-file-system/next';

try {
  const file = new File(Paths.cache, 'example.txt');
  const content = await FileSystem.readAsStringAsync(file.uri);
  console.log(content);
} catch (error) {
  console.error(error);
}
```

### Listing directory contents recursively

```ts
import { Directory, Paths } from 'expo-file-system/next';

function printDirectory(directory: Directory, indent: number = 0) {
  console.log(`${' '.repeat(indent)} + ${directory.name}`);
  const contents = directory.list();
  for (const item of contents) {
    if (item instanceof Directory) {
      printDirectory(item, indent + 2);
    } else {
      console.log(`${' '.repeat(indent + 2)} - ${item.name} (${item.size} bytes)`);
    }
  }
}

try {
  printDirectory(new Directory(Paths.cache));
} catch (error) {
  console.error(error);
}
```

## API

## Classes

### `Directory`

Supported platforms: Android, iOS, tvOS.

Type: Class extends `FileSystemDirectory`

Represents a directory on the filesystem.

A `Directory` instance can be created for any path, and does not need to exist on the filesystem during creation.

Directory Properties

### `exists`

Supported platforms: Android, iOS, tvOS.

Type: `boolean`

A boolean representing if a directory exists. `true` if the directory exists, `false` otherwise. Also, `false` if the application does not have read access to the file.

### `uri`

Supported platforms: Android, iOS, tvOS.

Read Only • Type: `string`

Represents the directory URI. The field is read-only, but it may change as a result of calling some methods such as `move`.

### `name`

Supported platforms: Android, iOS, tvOS.

Type: `string`

Directory name.

### `parentDirectory`

Supported platforms: Android, iOS, tvOS.

Type: [Directory](#directory)

Directory containing the file.

Directory Methods

### `copy(destination)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type |
| --- | --- |
| `destination` | [Directory](#directory) | [File](#file) |

  

Copies a directory.

Returns: `void`

### `create(options)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type |
| --- | --- |
| `options`(optional) | [CreateOptions](#createoptions) |

  

Creates a directory that the current uri points to.

Returns: `void`

### `delete()`

Supported platforms: Android, iOS, tvOS.

Deletes a directory. Also deletes all files and directories inside the directory.

Returns: `void`

### `list()`

Supported platforms: Android, iOS, tvOS.

Lists the contents of a directory. Calling this method if the parent directory does not exist will throw an error.

Returns: `(File | Directory)[]`

An array of `Directory` and `File` instances.

### `move(destination)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type |
| --- | --- |
| `destination` | [Directory](#directory) | [File](#file) |

  

Moves a directory. Updates the `uri` property that now points to the new location.

Returns: `void`

### `File`

Supported platforms: Android, iOS, tvOS.

Type: Class extends `FileSystemFile`

File Properties

### `exists`

Supported platforms: Android, iOS, tvOS.

Type: `boolean`

A boolean representing if a file exists. `true` if the file exists, `false` otherwise. Also, `false` if the application does not have read access to the file.

### `md5`

Supported platforms: Android, iOS, tvOS.

Literal type: `union`

A md5 hash of the file. Null if the file does not exist, or it cannot be read.

Acceptable values are: `null` | `string`

### `size`

Supported platforms: Android, iOS, tvOS.

Literal type: `union`

A size of the file in bytes. Null if the file does not exist, or it cannot be read.

Acceptable values are: `null` | `number`

### `type`

Supported platforms: Android, iOS, tvOS.

Literal type: `union`

A mime type of the file. Null if the file does not exist, or it cannot be read.

Acceptable values are: `null` | `string`

### `uri`

Supported platforms: Android, iOS, tvOS.

Read Only • Type: `string`

Represents the file URI. The field is read-only, but it may change as a result of calling some methods such as `move`.

### `extension`

Supported platforms: Android, iOS, tvOS.

Type: `string`

File extension.

Example

`'.png'`

### `name`

Supported platforms: Android, iOS, tvOS.

Type: `string`

File name. Includes the extension.

### `parentDirectory`

Supported platforms: Android, iOS, tvOS.

Type: [Directory](#directory)

Directory containing the file.

File Methods

### `base64()`

Supported platforms: Android, iOS, tvOS.

Retrieves content of the file as base64.

Returns: `string`

The contents of the file as a base64 string.

### `blob()`

Supported platforms: Android, iOS, tvOS.

Returns the file as a `Blob`. The blob can be used in `@expo/fetch` to send files over network and for other uses.

Returns: `Blob`

### `bytes()`

Supported platforms: Android, iOS, tvOS.

Retrieves byte content of the entire file.

Returns: `Uint8Array`

The contents of the file as a Uint8Array.

### `copy(destination)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type |
| --- | --- |
| `destination` | [Directory](#directory) | [File](#file) |

  

Copies a file.

Returns: `void`

### `create(options)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type |
| --- | --- |
| `options`(optional) | [CreateOptions](#createoptions) |

  

Creates a file.

Returns: `void`

### `delete()`

Supported platforms: Android, iOS, tvOS.

Deletes a file.

Returns: `void`

### `downloadFileAsync(url, destination)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type | Description |
| --- | --- | --- |
| `url` | `string` | The URL of the file to download. |
| `destination` | [Directory](#directory) | [File](#file) | The destination directory or file. If a directory is provided, the resulting filename will be determined based on the response headers. |

  

A static method that downloads a file from the network.

Returns: `Promise<file>`

A promise that resolves to the downloaded file.

Example

```ts
const file = await File.downloadFileAsync("https://example.com/image.png", new Directory(Paths.document));
```

### `move(destination)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type |
| --- | --- |
| `destination` | [Directory](#directory) | [File](#file) |

  

Moves a directory. Updates the `uri` property that now points to the new location.

Returns: `void`

### `open()`

Supported platforms: Android, iOS, tvOS.

Returns a FileHandle object that can be used to read and write data to the file.

Returns: `FileHandle`

### `readableStream()`

Supported platforms: Android, iOS, tvOS.

Returns: `ReadableStream<uint8array>`

### `text()`

Supported platforms: Android, iOS, tvOS.

Retrieves text from the file.

Returns: `string`

The contents of the file as string.

### `writableStream()`

Supported platforms: Android, iOS, tvOS.

Returns: `WritableStream<uint8array>`

### `write(content)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type | Description |
| --- | --- | --- |
| `content` | string | [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) | The content to write into the file. |

  

Writes content to the file.

Returns: `void`

### `FileHandle`

Supported platforms: Android, iOS, tvOS.

FileHandle Properties

### `offset`

Supported platforms: Android, iOS, tvOS.

Literal type: `union`

A property that indicates the current byte offset in the file. Calling `readBytes` or `writeBytes` will read or write a specified amount of bytes starting from this offset. The offset is incremented by the number of bytes read or written. The offset can be set to any value within the file size. If the offset is set to a value greater than the file size, the next write operation will append data to the end of the file. Null if the file handle is closed.

Acceptable values are: `null` | `number`

### `size`

Supported platforms: Android, iOS, tvOS.

Literal type: `union`

A size of the file in bytes or `null` if the file handle is closed.

Acceptable values are: `null` | `number`

FileHandle Methods

### `close()`

Supported platforms: Android, iOS, tvOS.

Closes the file handle. This allows the file to be deleted, moved or read by a different process. Subsequent calls to `readBytes` or `writeBytes` will throw an error.

Returns: `void`

### `readBytes(length)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type | Description |
| --- | --- | --- |
| `length` | `number` | The number of bytes to read. |

  

Reads the specified amount of bytes from the file at the current offset.

Returns: `Uint8Array`

### `writeBytes(bytes)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type | Description |
| --- | --- | --- |
| `bytes` | [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) | A `Uint8Array` array containing bytes to write. |

  

Writes the specified bytes to the file at the current offset.

Returns: `void`

### `Paths`

Supported platforms: Android, iOS, tvOS.

Type: Class extends `PathUtilities`

Paths Properties

### `appleSharedContainers`

Supported platforms: Android, iOS, tvOS.

Type: Record<string, [Directory](#directory)\>

### `cache`

Supported platforms: Android, iOS, tvOS.

Type: [Directory](#directory)

A property containing the cache directory – a place to store files that can be deleted by the system when the device runs low on storage.

### `document`

Supported platforms: Android, iOS, tvOS.

Type: [Directory](#directory)

A property containing the document directory – a place to store files that are safe from being deleted by the system.

Paths Methods

### `basename(path, ext)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type | Description |
| --- | --- | --- |
| `path` | string | [File](#file) | [Directory](#directory) | The path to get the base name from. |
| `ext`(optional) | `string` | An optional file extension. |

  

Returns the base name of a path.

Returns: `string`

A string representing the base name.

### `dirname(path)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type | Description |
| --- | --- | --- |
| `path` | string | [File](#file) | [Directory](#directory) | The path to get the directory name from. |

  

Returns the directory name of a path.

Returns: `string`

A string representing the directory name.

### `extname(path)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type | Description |
| --- | --- | --- |
| `path` | string | [File](#file) | [Directory](#directory) | The path to get the extension from. |

  

Returns the extension of a path.

Returns: `string`

A string representing the extension.

### `isAbsolute(path)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type | Description |
| --- | --- | --- |
| `path` | string | [File](#file) | [Directory](#directory) | The path to check. |

  

Checks if a path is absolute.

Returns: `boolean`

`true` if the path is absolute, `false` otherwise.

### `join(...paths)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type | Description |
| --- | --- | --- |
| `. .paths` | (string | [File](#file) | [Directory](#directory))[] | An array of path segments. |

  

Joins path segments into a single path.

Returns: `string`

A string representing the joined path.

### `normalize(path)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type | Description |
| --- | --- | --- |
| `path` | string | [File](#file) | [Directory](#directory) | The path to normalize. |

  

Normalizes a path.

Returns: `string`

A string representing the normalized path.

### `parse(path)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type | Description |
| --- | --- | --- |
| `path` | string | [File](#file) | [Directory](#directory) | The path to parse. |

  

Parses a path into its components.

Returns: `{ base: string, dir: string, ext: string, name: string, root: string }`

An object containing the parsed path components.

### `relative(from, to)`

Supported platforms: Android, iOS, tvOS.

| Parameter | Type | Description |
| --- | --- | --- |
| `from` | string | [File](#file) | [Directory](#directory) | The base path. |
| `to` | string | [File](#file) | [Directory](#directory) | The relative path. |

  

Resolves a relative path to an absolute path.

Returns: `string`

A string representing the resolved path.

## Types

### `CreateOptions`

Supported platforms: Android, iOS, tvOS.

| Property | Type | Description |
| --- | --- | --- |
| intermediates(optional) | `boolean` | Whether to create intermediate directories if they do not exist. Default: `false` |
| overwrite(optional) | `boolean` | Whether to overwrite the file or directory if it exists. Default: `false` |