Skip to main content

filesystem

Library

Provides functions to interact with the local filesystem.

Functions​

writefile​

</>
filesystem.writefile(
path: string,--

The path to the file.

content: string | buffer--

The content to write to the file.

) → ()

Writes content (string or buffer) to a specified file. Creates the file if it does not exist, and overwrites it if it does.

Paths

Paths should ideally be relative to a designated workspace or root directory defined by the executor environment. Absolute paths are restricted.

Errors

TypeDescription
Cannot write to file '%s'The file could not be written to due to permissions or other OS-level issues.

readfile​

</>
filesystem.readfile(
path: string,--

The path to the file.

asBuffer: boolean?--

If true, return content as a buffer; if false (default), return as a string.

) → string | buffer--

The content of the file, either as a string or a buffer based on the asBuffer flag.

Reads the content of a specified file, returning it as a string or a buffer.

Errors

TypeDescription
Cannot read file '%s'The file does not exist or cannot be read due to permissions.

loadfile​

</>
filesystem.loadfile(
path: string--

The path to the Lua file.

) → (
((...any) → ...any) | nil,--

The loaded chunk as a function, or nil if loading failed.

string?--

An error message if loading failed.

)

Loads a Lua chunk from the specified file but does not run it.

Environment

The loaded chunk inherits the environment of the caller.

loadstring

This function behaves similarly to loadstring but operates on file paths instead of raw strings. Refer to closures.loadstring for potential compilation settings.

Errors

TypeDescription
Cannot read file '%s'The file does not exist or cannot be read due to permissions.

dofile​

</>
filesystem.dofile(
path: string--

The path to the Lua file.

) → ...any--

The values returned by the executed chunk.

Loads and runs a Lua chunk from the specified file.

Environment

The executed chunk inherits the environment of the caller.

Errors

TypeDescription
Cannot read file '%s'The file does not exist or cannot be read due to permissions.
...Any runtime error originating from the executed chunk.

delfile​

</>
filesystem.delfile(
path: string--

The path to the file to delete.

) → ()

Deletes a specified file.

Errors

TypeDescription
Cannot delete file '%s'The file does not exist, cannot be deleted due to permissions, or the path isn't a file or other issues.

appendfile​

</>
filesystem.appendfile(
path: string,--

The path to the file.

content: string | buffer--

The content to append to the file.

) → ()

Appends content (string or buffer) to the end of a specified file. Creates the file if it does not exist.

Errors

TypeDescription
Cannot append to file '%s'The file could not be appended to due to permissions or other OS-level issues.

movefile​

</>
filesystem.movefile(
oldpath: string,--

The current path of the file.

newpath: string--

The desired new path for the file.

) → ()

Moves or renames a file. Does not work on folders.

Behavior

If newpath already exists, it will overwrite it. Use movefolder for directories.

Errors

TypeDescription
Cannot move file from '%s' to '%s'Failed due to permissions, item not found, `oldpath` is a folder, target path invalid, or other OS issues.

movefolder​

</>
filesystem.movefolder(
oldpath: string,--

The current path of the folder.

newpath: string--

The desired new path for the folder.

) → ()

Moves or renames a folder. Does not work on files.

Behavior

If newpath already exists, it will overwrite it. Use movefile for files.

Errors

TypeDescription
Cannot move folder from '%s' to '%s'Failed due to permissions, item not found, `oldpath` is a file, target path invalid, or other OS issues.

copyfile​

</>
filesystem.copyfile(
sourcepath: string,--

The path of the file to copy.

destinationpath: string--

The path where the copy should be created.

) → ()

Copies a file.

Behavior

If destinationpath already exists, it will likely be overwritten. This function typically only works for files. For copying folders, use copyfolder.

Errors

TypeDescription
Cannot copy file from '%s' to '%s'Failed due to permissions, source not found, destination path invalid, or other OS issues.

copyfolder​

</>
filesystem.copyfolder(
sourcepath: string,--

The path of the folder to copy.

destinationpath: string--

The path where the copied folder should be created.

) → ()

Recursively copies a folder and its contents.

Behavior

If destinationpath already exists as a folder, the contents of sourcepath might be merged into it, or it might error, depending on implementation. If destinationpath exists as a file, it will error. This function recursively copies all subfolders and files. Use copyfile for single files.

Errors

TypeDescription
Cannot copy folder from '%s' to '%s'Failed due to permissions, source not found, `sourcepath` is a file, destination path invalid, or other OS issues during recursion.

listfiles​

</>
filesystem.listfiles(
path: string,--

The path to the directory.

options: ListfilesOptions?--

A table containing options like Recursive (boolean, default false) and Hidden (boolean, default true).

) → {string}--

A list of names (or relative paths if recursive) of files and folders within the directory.

Lists all files and folders within a specified directory path according to the provided options.

Errors

TypeDescription
Cannot list directory '%s'The directory does not exist or cannot be accessed.

isfile​

</>
filesystem.isfile(
path: string--

The path to check.

) → boolean--

True if the path points to an existing file, false otherwise.

Checks if a given path points to an existing file.

isfolder​

</>
filesystem.isfolder(
path: string--

The path to check.

) → boolean--

True if the path points to an existing folder, false otherwise.

Checks if a given path points to an existing folder (directory).

makefolder​

</>
filesystem.makefolder(
path: string--

The path where the folder should be created.

) → ()

Creates a new folder (directory) at the specified path.

Errors

TypeDescription
Cannot create folder '%s'The folder could not be created (e.g., path already exists as a file, permissions issue, invalid path).

delfolder​

</>
filesystem.delfolder(
path: string--

The path to the folder to delete.

) → ()

Deletes a specified folder (directory) and all of its contents recursively.

Behavior

This function permanently deletes the specified folder and all files and subfolders within it. Use with caution.

Errors

TypeDescription
Cannot delete folder '%s'The folder does not exist, cannot be deleted due to permissions, or the path isn't a folder or other issues (e.g., a file within is locked).

getproperties​

</>
filesystem.getproperties(
path: string--

The path to the file or folder.

) → ItemProperties?--

A table containing properties (size, creation time, last modified time, hidden, read-only), or nil if the path does not exist. Size will always be 0 for folders.

Retrieves properties of a specified file or folder.

Errors

TypeDescription
Cannot get properties for '%s'Permissions error or other OS issue preventing access.

setproperties​

</>
filesystem.setproperties(
path: string,--

The path to the file or folder.

properties: ItemProperties--

A table containing the properties to set. Only IsHidden and IsReadOnly are typically settable for both files and folders. Other properties in the table are ignored.

) → ()

Sets modifiable properties of a specified file or folder.

Settable Properties

Generally, only the IsHidden and IsReadOnly flags can be reliably modified. Timestamps and size are usually managed by the OS. The function should ideally ignore attempts to set read-only properties specified in the input table. The effect of IsReadOnly on folders may vary by OS.

Errors

TypeDescription
Cannot set properties for '%s'The path does not exist, permissions error, or property modification failed.

getcustomasset​

</>
filesystem.getcustomasset(
path: string--

The path to the local asset file.

) → string--

A Roblox asset URL (e.g., rbxasset://some_generated_identifier).

Takes a path to a local file (e.g., an image) and returns a Roblox content URL (e.g., rbxasset://<filehash>) that can be used to load the asset within Roblox interfaces.

Usage

This function allows importing local files (like images, sounds, etc.) for use in Roblox UIs or parts by converting them into a temporary or cached asset URL recognized by the engine. The underlying mechanism might involve hashing the file content or uploading it to a temporary storage accessible by the client.

Errors

TypeDescription
Cannot process asset '%s'The file does not exist or could not be processed.
Show raw api
{
    "functions": [
        {
            "name": "writefile",
            "desc": "Writes content (string or buffer) to a specified file. Creates the file if it does not exist, and overwrites it if it does.\n\n\n:::info Paths\nPaths should ideally be relative to a designated workspace or root directory defined by the executor environment. Absolute paths are restricted.\n:::",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to the file.",
                    "lua_type": "string"
                },
                {
                    "name": "content",
                    "desc": "The content to write to the file.",
                    "lua_type": "string | buffer"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot write to file '%s'",
                    "desc": "The file could not be written to due to permissions or other OS-level issues."
                }
            ],
            "source": {
                "line": 21,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "readfile",
            "desc": "Reads the content of a specified file, returning it as a string or a buffer.",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to the file.",
                    "lua_type": "string"
                },
                {
                    "name": "asBuffer",
                    "desc": "If true, return content as a buffer; if false (default), return as a string.",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [
                {
                    "desc": "The content of the file, either as a string or a buffer based on the asBuffer flag.",
                    "lua_type": "string | buffer"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot read file '%s'",
                    "desc": "The file does not exist or cannot be read due to permissions."
                }
            ],
            "source": {
                "line": 32,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "loadfile",
            "desc": "Loads a Lua chunk from the specified file but does not run it.\n\n\n:::info Environment\nThe loaded chunk inherits the environment of the caller.\n:::\n\n:::tip `loadstring`\nThis function behaves similarly to `loadstring` but operates on file paths instead of raw strings. Refer to `closures.loadstring` for potential compilation settings.\n:::",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to the Lua file.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "The loaded chunk as a function, or nil if loading failed.",
                    "lua_type": "((...any) -> ...any) | nil"
                },
                {
                    "desc": "An error message if loading failed.",
                    "lua_type": "string?"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot read file '%s'",
                    "desc": "The file does not exist or cannot be read due to permissions."
                }
            ],
            "source": {
                "line": 53,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "dofile",
            "desc": "Loads and runs a Lua chunk from the specified file.\n\n\n:::info Environment\nThe executed chunk inherits the environment of the caller.\n:::",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to the Lua file.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "The values returned by the executed chunk.",
                    "lua_type": "...any"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot read file '%s'",
                    "desc": "The file does not exist or cannot be read due to permissions."
                },
                {
                    "lua_type": "...",
                    "desc": "Any runtime error originating from the executed chunk."
                }
            ],
            "source": {
                "line": 70,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "delfile",
            "desc": "Deletes a specified file.",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to the file to delete.",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot delete file '%s'",
                    "desc": "The file does not exist, cannot be deleted due to permissions, or the path isn't a file or other issues."
                }
            ],
            "source": {
                "line": 81,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "appendfile",
            "desc": "Appends content (string or buffer) to the end of a specified file. Creates the file if it does not exist.",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to the file.",
                    "lua_type": "string"
                },
                {
                    "name": "content",
                    "desc": "The content to append to the file.",
                    "lua_type": "string | buffer"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot append to file '%s'",
                    "desc": "The file could not be appended to due to permissions or other OS-level issues."
                }
            ],
            "source": {
                "line": 91,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "movefile",
            "desc": "Moves or renames a file. Does **not** work on folders.\n\n\n:::warning Behavior\nIf `newpath` already exists, it will overwrite it. Use `movefolder` for directories.\n:::",
            "params": [
                {
                    "name": "oldpath",
                    "desc": "The current path of the file.",
                    "lua_type": "string"
                },
                {
                    "name": "newpath",
                    "desc": "The desired new path for the file.",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot move file from '%s' to '%s'",
                    "desc": "Failed due to permissions, item not found, `oldpath` is a folder, target path invalid, or other OS issues."
                }
            ],
            "source": {
                "line": 105,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "movefolder",
            "desc": "Moves or renames a folder. Does **not** work on files.\n\n\n:::warning Behavior\nIf `newpath` already exists, it will overwrite it. Use `movefile` for files.\n:::",
            "params": [
                {
                    "name": "oldpath",
                    "desc": "The current path of the folder.",
                    "lua_type": "string"
                },
                {
                    "name": "newpath",
                    "desc": "The desired new path for the folder.",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot move folder from '%s' to '%s'",
                    "desc": "Failed due to permissions, item not found, `oldpath` is a file, target path invalid, or other OS issues."
                }
            ],
            "source": {
                "line": 119,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "copyfile",
            "desc": "Copies a file.\n\n\n:::warning Behavior\nIf `destinationpath` already exists, it will likely be overwritten. This function typically only works for files. For copying folders, use `copyfolder`.\n:::",
            "params": [
                {
                    "name": "sourcepath",
                    "desc": "The path of the file to copy.",
                    "lua_type": "string"
                },
                {
                    "name": "destinationpath",
                    "desc": "The path where the copy should be created.",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot copy file from '%s' to '%s'",
                    "desc": "Failed due to permissions, source not found, destination path invalid, or other OS issues."
                }
            ],
            "source": {
                "line": 133,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "copyfolder",
            "desc": "Recursively copies a folder and its contents.\n\n\n:::warning Behavior\nIf `destinationpath` already exists as a folder, the contents of `sourcepath` might be merged into it, or it might error, depending on implementation. If `destinationpath` exists as a file, it will error. This function recursively copies all subfolders and files. Use `copyfile` for single files.\n:::",
            "params": [
                {
                    "name": "sourcepath",
                    "desc": "The path of the folder to copy.",
                    "lua_type": "string"
                },
                {
                    "name": "destinationpath",
                    "desc": "The path where the copied folder should be created.",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot copy folder from '%s' to '%s'",
                    "desc": "Failed due to permissions, source not found, `sourcepath` is a file, destination path invalid, or other OS issues during recursion."
                }
            ],
            "source": {
                "line": 147,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "listfiles",
            "desc": "Lists all files and folders within a specified directory path according to the provided options.",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to the directory.",
                    "lua_type": "string"
                },
                {
                    "name": "options",
                    "desc": "A table containing options like `Recursive` (boolean, default false) and `Hidden` (boolean, default true).",
                    "lua_type": "ListfilesOptions?"
                }
            ],
            "returns": [
                {
                    "desc": "A list of names (or relative paths if recursive) of files and folders within the directory.",
                    "lua_type": "{string}"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot list directory '%s'",
                    "desc": "The directory does not exist or cannot be accessed."
                }
            ],
            "source": {
                "line": 158,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "isfile",
            "desc": "Checks if a given path points to an existing file.",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to check.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "True if the path points to an existing file, false otherwise.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 169,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "isfolder",
            "desc": "Checks if a given path points to an existing folder (directory).",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to check.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "True if the path points to an existing folder, false otherwise.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 180,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "makefolder",
            "desc": "Creates a new folder (directory) at the specified path.",
            "params": [
                {
                    "name": "path",
                    "desc": "The path where the folder should be created.",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot create folder '%s'",
                    "desc": "The folder could not be created (e.g., path already exists as a file, permissions issue, invalid path)."
                }
            ],
            "source": {
                "line": 191,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "delfolder",
            "desc": "Deletes a specified folder (directory) and all of its contents recursively.\n\n\n:::warning Behavior\nThis function permanently deletes the specified folder and **all** files and subfolders within it. Use with caution.\n:::",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to the folder to delete.",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot delete folder '%s'",
                    "desc": "The folder does not exist, cannot be deleted due to permissions, or the path isn't a folder or other issues (e.g., a file within is locked)."
                }
            ],
            "source": {
                "line": 204,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "getproperties",
            "desc": "Retrieves properties of a specified file or folder.",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to the file or folder.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "A table containing properties (size, creation time, last modified time, hidden, read-only), or nil if the path does not exist. Size will always be `0` for folders.",
                    "lua_type": "ItemProperties?"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot get properties for '%s'",
                    "desc": "Permissions error or other OS issue preventing access."
                }
            ],
            "source": {
                "line": 214,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "setproperties",
            "desc": "Sets modifiable properties of a specified file or folder.\n\n\n:::info Settable Properties\nGenerally, only the `IsHidden` and `IsReadOnly` flags can be reliably modified. Timestamps and size are usually managed by the OS. The function should ideally ignore attempts to set read-only properties specified in the input table. The effect of `IsReadOnly` on folders may vary by OS.\n:::",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to the file or folder.",
                    "lua_type": "string"
                },
                {
                    "name": "properties",
                    "desc": "A table containing the properties to set. Only `IsHidden` and `IsReadOnly` are typically settable for both files and folders. Other properties in the table are ignored.",
                    "lua_type": "ItemProperties"
                }
            ],
            "returns": [],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot set properties for '%s'",
                    "desc": "The path does not exist, permissions error, or property modification failed."
                }
            ],
            "source": {
                "line": 230,
                "path": "impl/Libraries/filesystem.luau"
            }
        },
        {
            "name": "getcustomasset",
            "desc": "Takes a path to a local file (e.g., an image) and returns a Roblox content URL (e.g., `rbxasset://<filehash>`) that can be used to load the asset within Roblox interfaces.\n\n\n:::info Usage\nThis function allows importing local files (like images, sounds, etc.) for use in Roblox UIs or parts by converting them into a temporary or cached asset URL recognized by the engine. The underlying mechanism might involve hashing the file content or uploading it to a temporary storage accessible by the client.\n:::",
            "params": [
                {
                    "name": "path",
                    "desc": "The path to the local asset file.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "A Roblox asset URL (e.g., `rbxasset://some_generated_identifier`).",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "errors": [
                {
                    "lua_type": "Cannot process asset '%s'",
                    "desc": "The file does not exist or could not be processed."
                }
            ],
            "source": {
                "line": 244,
                "path": "impl/Libraries/filesystem.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "filesystem",
    "desc": "Provides functions to interact with the local filesystem.",
    "tags": [
        "Library"
    ],
    "source": {
        "line": 7,
        "path": "impl/Libraries/filesystem.luau"
    }
}