Reference version

Expo FileSystem iconExpo FileSystem

GitHub

Changelog

npm

A library that provides access to the local file system on the device.

Android
iOS
tvOS
Bundled version:
~19.0.1

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

Installation

Terminal
npx expo install expo-file-system

If you are installing this in an existing React Native app, make sure to install expo in your project.

Usage

Writing and reading text files

example.ts
import { File, Paths } from 'expo-file-system'; 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:

example.ts
import { Directory, File, Paths } from 'expo-file-system'; 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:

example.ts
import { fetch } from 'expo/fetch'; import { File } from 'expo-file-system'; const url = 'https://pdfobject.com/pdf/sample.pdf'; const response = await fetch(url); const src = new File(testDirectory, '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:

example.ts
import { fetch } from 'expo/fetch'; import { File } from 'expo-file-system'; const src = new File(testDirectory, 'file.txt'); file.write('Hello, world!'); const blob = src.blob(); const response = await fetch('https://example.com', { method: 'POST', body: blob, });

Or using the FormData constructor:

example.ts
import { fetch } from 'expo/fetch'; const src = new File(testDirectory, 'file.txt'); file.write('Hello, world!'); const blob = src.blob(); const formData = new FormData(); formData.append('data', blob); const response = await fetch('https://example.com', { method: 'POST', body: formData, });

Moving and copying files

example.ts
import { Directory, File, Paths } from 'expo-file-system'; try { const file = new File(Paths.document, 'example.txt'); file.create(); console.log(file.uri); // '${documentDirectory}/example.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

example.ts
import * as FileSystem from 'expo-file-system/legacy'; import { File, Paths } from 'expo-file-system'; 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

example.ts
import { Directory, Paths } from 'expo-file-system'; 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

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

Type: boolean

A boolean representing if a directory exists and can be accessed.

size

Literal type: union

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

Acceptable values are: null | number

uri

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

Type: string

Directory name.

parentDirectory

Type: Directory

Directory containing the file.

Directory Methods

copy(destination)

ParameterType
destinationDirectory | File

Copies a directory.

Returns:
void

create(options)

ParameterType
options(optional)CreateOptions

Creates a directory that the current uri points to.

Returns:
void

createDirectory(name)

ParameterType
namestring

Returns:
Directory

createFile(name, mimeType)

ParameterType
namestring
mimeTypenull | string

Returns:
File

delete()

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

Returns:
void

info()

Retrieves an object containing properties of a directory

An object with directory metadata (e.g., size, creation date, etc.).

list()

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)

ParameterType
destinationDirectory | File

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

Returns:
void

File

Type: Class extends FileSystemFile implements Blob

File Properties

creationTime

Literal type: union

A creation time of the file expressed in milliseconds since epoch. Returns null if the file does not exist, cannot be read or the Android version is earlier than API 26.

Acceptable values are: null | number

exists

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

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

modificationTime

Literal type: union

A last modification time of the file expressed in milliseconds since epoch. Returns a Null if the file does not exist, or it cannot be read.

Acceptable values are: null | number

uri

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

Type: string

File extension.

Example

'.png'

name

Type: string

File name. Includes the extension.

parentDirectory

Type: Directory

Directory containing the file.

File Methods

base64()

Retrieves content of the file as base64.

Returns:
string

A promise that resolves with the contents of the file as a base64 string.

base64Sync()

Retrieves content of the file as base64.

Returns:
string

The contents of the file as a base64 string.

bytesSync()

Retrieves byte content of the entire file.

Returns:
Uint8Array

A promise that resolves with the contents of the file as a Uint8Array.

copy(destination)

ParameterType
destinationDirectory | File

Copies a file.

Returns:
void

create(options)

ParameterType
options(optional)CreateOptions

Creates a file.

Returns:
void

delete()

Deletes a file.

Returns:
void

downloadFileAsync(url, destination, options)

ParameterTypeDescription
urlstring

The URL of the file to download.

destinationDirectory | File

The destination directory or file. If a directory is provided, the resulting filename will be determined based on the response headers.

options(optional)DownloadOptions
-

A static method that downloads a file from the network.

Returns:
Promise<File>

A promise that resolves to the downloaded file.

Example

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

info(options)

ParameterType
options(optional)InfoOptions

Retrieves an object containing properties of a file

Returns:
FileInfo

An object with file metadata (e.g., size, creation date, etc.).

move(destination)

ParameterType
destinationDirectory | File

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

Returns:
void

open()

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

Returns:
FileHandle

readableStream()

textSync()

Retrieves text from the file.

Returns:
Promise<string>

The contents of the file as string.

writableStream()

write(content)

ParameterTypeDescription
contentstring | Uint8Array

The content to write into the file.


Writes content to the file.

Returns:
void

FileHandle

FileHandle Properties

offset

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

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()

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)

ParameterTypeDescription
lengthnumber

The number of bytes to read.


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

writeBytes(bytes)

ParameterTypeDescription
bytesUint8Array

A Uint8Array array containing bytes to write.


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

Returns:
void

Paths

Type: Class extends PathUtilities

Paths Properties

appleSharedContainers

Type: Record<string, Directory>

availableDiskSpace

Type: number

A property that represents the available space on device's internal storage, represented in bytes.

bundle

Type: Directory

A property containing the bundle directory – the directory where assets bundled with the application are stored.

cache

Type: 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

Type: Directory

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

totalDiskSpace

Type: number

A property that represents the total space on device's internal storage, represented in bytes.

Paths Methods

basename(path, ext)

ParameterTypeDescription
pathstring | File | 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)

ParameterTypeDescription
pathstring | File | 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)

ParameterTypeDescription
pathstring | File | Directory

The path to get the extension from.


Returns the extension of a path.

Returns:
string

A string representing the extension.

info(...uris)

ParameterType
...urisstring[]

Returns an object that indicates if the specified path represents a directory.

Returns:
PathInfo

isAbsolute(path)

ParameterTypeDescription
pathstring | File | Directory

The path to check.


Checks if a path is absolute.

Returns:
boolean

true if the path is absolute, false otherwise.

join(...paths)

ParameterTypeDescription
...paths(string | File | Directory)[]

An array of path segments.


Joins path segments into a single path.

Returns:
string

A string representing the joined path.

normalize(path)

ParameterTypeDescription
pathstring | File | Directory

The path to normalize.


Normalizes a path.

Returns:
string

A string representing the normalized path.

parse(path)

ParameterTypeDescription
pathstring | File | 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)

ParameterTypeDescription
fromstring | File | Directory

The base path.

tostring | File | Directory

The relative path.


Resolves a relative path to an absolute path.

Returns:
string

A string representing the resolved path.

Types

CreateOptions

PropertyTypeDescription
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

DirectoryInfo

PropertyTypeDescription
creationTime(optional)number

A creation time of the directory expressed in milliseconds since epoch. Returns null if the Android version is earlier than API 26.

existsboolean

Indicates whether the directory exists.

files(optional)string[]

A list of file names contained within a directory.

modificationTime(optional)number

The last modification time of the directory expressed in milliseconds since epoch.

size(optional)number

The size of the file in bytes.

uri(optional)string

A file:// URI pointing to the directory.

FileInfo

PropertyTypeDescription
creationTime(optional)number

A creation time of the file expressed in milliseconds since epoch. Returns null if the Android version is earlier than API 26.

existsboolean

Indicates whether the file exists.

md5(optional)string

Present if the md5 option was truthy. Contains the MD5 hash of the file.

modificationTime(optional)number

The last modification time of the file expressed in milliseconds since epoch.

size(optional)number

The size of the file in bytes.

uri(optional)string

A file:// URI pointing to the file. This is the same as the fileUri input parameter.

InfoOptions

PropertyTypeDescription
md5(optional)boolean

Whether to return the MD5 hash of the file.

Default:false

PathInfo

PropertyTypeDescription
existsboolean

Indicates whether the path exists. Returns true if it exists; false if the path does not exist or if there is no read permission.

isDirectoryboolean | null

Indicates whether the path is a directory. Returns true or false if the path exists; otherwise, returns null.