fs

Interact with the computer's files and filesystem, allowing you to manipulate files, directories and paths. This includes:

• Reading and writing files: Call open to obtain a file "handle", which can be used to read from or write to a file.
• Path manipulation: combine, getName and getDir allow you to manipulate file paths, joining them together or extracting components.
• Querying paths: For instance, checking if a file exists, or whether it's a directory. See getSize, exists, isDir, isReadOnly and attributes.
• File and directory manipulation: For instance, moving or copying files. See makeDir, move, copy and delete.

Mounts

While a computer can only have one hard drive and filesystem, other filesystems may be "mounted" inside it. For instance, the drive peripheral mounts its disk's contents at "disk/", "disk1/", etc...

You can see which mount a path belongs to with the getDrive function. This returns "hdd" for the computer's main filesystem ("/"), "rom" for the rom ("rom/").

Most filesystems have a limited capacity, operations which would cause that capacity to be reached (such as writing an incredibly large file) will fail. You can see a mount's capacity with getCapacity and the remaining space with getFreeSpace.

complete(...)Source

Provides completion for a file or directory name, suitable for use with _G.read.

When a directory is a possible candidate for completion, two entries are included - one with a trailing slash (indicating that entries within this directory exist) and one without it (meaning this entry is an immediate completion candidate). include_dirs can be set to false to only include those with a trailing slash.

Parameters

1. path string The path to complete.
2. location string The location where paths are resolved from.
3. include_files? boolean = true When false, only directories will be included in the returned list.
4. include_dirs? boolean = true When false, "raw" directories will not be included in the returned list.

Or

1. path string The path to complete.
2. location string The location where paths are resolved from.
3. options { include_dirs? = boolean, include_files? = boolean, include_hidden? = boolean }

   This table form is an expanded version of the previous syntax. The include_files and include_dirs arguments from above are passed in as fields.

   This table also accepts the following options:

   • include_hidden: Whether to include hidden files (those starting with .) by default. They will still be shown when typing a ..

Returns

1. { string... } A list of possible completion candidates.

Usage

• Complete files in the root directory.

  read(nil, nil, function(str)
      return fs.complete(str, "", true, false)
  end)
  

• Complete files in the root directory, hiding hidden files by default.

  read(nil, nil, function(str)
      return fs.complete(str, "", {
          include_files = true,
          include_dirs = false,
          include_hidden = false,
      })
  end)
  

Changes

• New in version 1.74
• Changed in version 1.101.0

isDriveRoot(path)Source

Returns true if a path is mounted to the parent filesystem.

The root filesystem "/" is considered a mount, along with disk folders and the rom folder. Other programs (such as network shares) can exstend this to make other mount types by correctly assigning their return value for getDrive.

Parameters

1. path string The path to check.

Returns

1. boolean If the path is mounted, rather than a normal file/folder.

Throws

• If the path does not exist.

See also

• getDrive

Changes

• New in version 1.87.0

list(path)Source

Returns a list of files in a directory.

Parameters

1. path string The path to list.

Returns

1. { string... } A table with a list of files in the directory.

Throws

• If the path doesn't exist.

Usage

• List all files under /rom/

  local files = fs.list("/rom/")
  for i = 1, #files do
    print(files[i])
  end
  

combine(path, ...)Source

Combines several parts of a path into one full path, adding separators as needed.

Parameters

1. path string The first part of the path. For example, a parent directory path.
2. ... string Additional parts of the path to combine.

Returns

1. string The new path, with separators added between parts as needed.

Throws

• On argument errors.

Usage

• Combine several file paths together

  fs.combine("/rom/programs", "../apis", "parallel.lua")
  -- => rom/apis/parallel.lua
  

Changes

• Changed in version 1.95.0: Now supports multiple arguments.

getName(path)Source

Returns the file name portion of a path.

Parameters

1. path string The path to get the name from.

Returns

1. string The final part of the path (the file name).

Usage

• Get the file name of rom/startup.lua

  fs.getName("rom/startup.lua")
  -- => startup.lua
  

Changes

• New in version 1.2

getDir(path)Source

Returns the parent directory portion of a path.

Parameters

1. path string The path to get the directory from.

Returns

1. string The path with the final part removed (the parent directory).

Usage

• Get the directory name of rom/startup.lua

  fs.getDir("rom/startup.lua")
  -- => rom
  

Changes

• New in version 1.63

getSize(path)Source

Returns the size of the specified file.

Parameters

1. path string The file to get the file size of.

Returns

1. number The size of the file, in bytes.

Throws

• If the path doesn't exist.

Changes

• New in version 1.3

exists(path)Source

Returns whether the specified path exists.

Parameters

1. path string The path to check the existence of.

Returns

1. boolean Whether the path exists.

isDir(path)Source

Returns whether the specified path is a directory.

Parameters

1. path string The path to check.

Returns

1. boolean Whether the path is a directory.

isReadOnly(path)Source

Returns whether a path is read-only.

Parameters

1. path string The path to check.

Returns

1. boolean Whether the path cannot be written to.

makeDir(path)Source

Creates a directory, and any missing parents, at the specified path.

Parameters

1. path string The path to the directory to create.

Throws

• If the directory couldn't be created.

move(path, dest)Source

Moves a file or directory from one path to another.

Any parent directories are created as needed.

Parameters

1. path string The current file or directory to move from.
2. dest string The destination path for the file or directory.

Throws

• If the file or directory couldn't be moved.

copy(path, dest)Source

Copies a file or directory to a new path.

Any parent directories are created as needed.

Parameters

1. path string The file or directory to copy.
2. dest string The path to the destination file or directory.

Throws

• If the file or directory couldn't be copied.

delete(path)Source

Deletes a file or directory.

If the path points to a directory, all of the enclosed files and subdirectories are also deleted.

Parameters

1. path string The path to the file or directory to delete.

Throws

• If the file or directory couldn't be deleted.

open(path, mode)Source

Opens a file for reading or writing at a path.

The mode string can be any of the following:

• "r": Read mode
• "w": Write mode
• "a": Append mode

The mode may also have a "b" at the end, which opens the file in "binary mode". This allows you to read binary files, as well as seek within a file.

Parameters

1. path string The path to the file to open.
2. mode string The mode to open the file with.

Returns

1. table A file handle object for the file.

Or

1. nil If the file does not exist, or cannot be opened.
2. string | nil A message explaining why the file cannot be opened.

Throws

• If an invalid mode was specified.

Usage

• Read the contents of a file.

  local file = fs.open("/rom/help/intro.txt", "r")
  local contents = file.readAll()
  file.close()
  
  print(contents)
  

• Open a file and read all lines into a table. io.lines offers an alternative way to do this.

  local file = fs.open("/rom/motd.txt", "r")
  local lines = {}
  while true do
    local line = file.readLine()
  
    -- If line is nil then we've reached the end of the file and should stop
    if not line then break end
  
    lines[#lines + 1] = line
  end
  
  file.close()
  
  print(lines[math.random(#lines)]) -- Pick a random line and print it.
  

• Open a file and write some text to it. You can run edit out.txt to see the written text.

  local file = fs.open("out.txt", "w")
  file.write("Just testing some code")
  file.close() -- Remember to call close, otherwise changes may not be written!
  

getDrive(path)Source

Returns the name of the mount that the specified path is located on.

Parameters

1. path string The path to get the drive of.

Returns

1. string | nil The name of the drive that the file is on; e.g. hdd for local files, or rom for ROM files.

Throws

• If the path doesn't exist.

Usage

• Print the drives of a couple of mounts:

  print("/: " .. fs.getDrive("/"))
  print("/rom/: " .. fs.getDrive("rom"))
  

getFreeSpace(path)Source

Returns the amount of free space available on the drive the path is located on.

Parameters

1. path string The path to check the free space for.

Returns

1. number | "unlimited" The amount of free space available, in bytes, or "unlimited".

Throws

• If the path doesn't exist.

See also

• getCapacity To get the capacity of this drive.

Changes

• New in version 1.4

find(path)Source

Searches for files matching a string with wildcards.

This string is formatted like a normal path string, but can include any number of wildcards (*) to look for files matching anything. For example, rom/*/command* will look for any path starting with command inside any subdirectory of /rom.

Parameters

1. path string The wildcard-qualified path to search for.

Returns

1. { string... } A list of paths that match the search string.

Throws

• If the path doesn't exist.

Changes

• New in version 1.6

getCapacity(path)Source

Returns the capacity of the drive the path is located on.

Parameters

1. path string The path of the drive to get.

Returns

1. number | nil This drive's capacity. This will be nil for "read-only" drives, such as the ROM or treasure disks.

Throws

• If the capacity cannot be determined.

See also

• getFreeSpace To get the free space available on this drive.

Changes

• New in version 1.87.0

attributes(path)Source

Get attributes about a specific file or folder.

The returned attributes table contains information about the size of the file, whether it is a directory, when it was created and last modified, and whether it is read only.

The creation and modification times are given as the number of milliseconds since the UNIX epoch. This may be given to os.date in order to convert it to more usable form.

Parameters

1. path string The path to get attributes for.

Returns

1. { size = number, isDir = boolean, isReadOnly = boolean, created = number, modified = number } The resulting attributes.

Throws

• If the path does not exist.

See also

• getSize If you only care about the file's size.
• isDir If you only care whether a path is a directory or not.

Changes

• New in version 1.87.0
• Changed in version 1.91.0: Renamed modification field to modified.
• Changed in version 1.95.2: Added isReadOnly to attributes.

Types

BinaryReadHandle

A file handle opened with fs.open with the "rb" mode.

BinaryReadHandle.read([count])Source

Read a number of bytes from this file.

Parameters

1. count? number The number of bytes to read. When absent, a single byte will be read as a number. This may be 0 to determine we are at the end of the file.

Returns

1. nil If we are at the end of the file.

Or

1. number The value of the byte read. This is returned when the count is absent.

Or

1. string The bytes read as a string. This is returned when the count is given.

Throws

• When trying to read a negative number of bytes.

• If the file has been closed.

Changes

• Changed in version 1.80pr1: Now accepts an integer argument to read multiple bytes, returning a string instead of a number.

BinaryReadHandle.readAll()Source

Read the remainder of the file.

Returns

1. string | nil The remaining contents of the file, or nil if we are at the end.

Throws

• If the file has been closed.

Changes

• New in version 1.80pr1

BinaryReadHandle.readLine([withTrailing])Source

Read a line from the file.

Parameters

1. withTrailing? boolean Whether to include the newline characters with the returned string. Defaults to false.

Returns

1. string | nil The read line or nil if at the end of the file.

Throws

• If the file has been closed.

Changes

• New in version 1.80pr1.9
• Changed in version 1.81.0: \r is now stripped.

BinaryReadHandle.seek([whence [, offset]])Source

Seek to a new position within the file, changing where bytes are written to. The new position is an offset given by offset, relative to a start position determined by whence:

• "set": offset is relative to the beginning of the file.
• "cur": Relative to the current position. This is the default.
• "end": Relative to the end of the file.

In case of success, seek returns the new file position from the beginning of the file.

Parameters

1. whence? string Where the offset is relative to.
2. offset? number The offset to seek to.

Returns

1. number The new position.

Or

1. nil If seeking failed.
2. string The reason seeking failed.

Throws

• If the file has been closed.

Changes

• New in version 1.80pr1.9

BinaryReadHandle.close()Source

Close this file, freeing any resources it uses.

Once a file is closed it may no longer be read or written to.

Throws

• If the file has already been closed.

ReadHandle

A file handle opened with fs.open with the "r" mode.

ReadHandle.readLine([withTrailing])Source

Read a line from the file.

Parameters

1. withTrailing? boolean Whether to include the newline characters with the returned string. Defaults to false.

Returns

1. string | nil The read line or nil if at the end of the file.

Throws

• If the file has been closed.

Changes

• Changed in version 1.81.0: Added option to return trailing newline.

ReadHandle.readAll()Source

Read the remainder of the file.

Returns

1. nil | string The remaining contents of the file, or nil if we are at the end.

Throws

• If the file has been closed.

ReadHandle.read([count])Source

Read a number of characters from this file.

Parameters

1. count? number The number of characters to read, defaulting to 1.

Returns

1. string | nil The read characters, or nil if at the of the file.

Throws

• When trying to read a negative number of characters.

• If the file has been closed.

Changes

• New in version 1.80pr1.4

ReadHandle.close()Source

Close this file, freeing any resources it uses.

Once a file is closed it may no longer be read or written to.

Throws

• If the file has already been closed.

WriteHandle

A file handle opened by fs.open using the "w" or "a" modes.

WriteHandle.write(value)Source

Write a string of characters to the file.

Parameters

1. value The value to write to the file.

Throws

• If the file has been closed.

WriteHandle.writeLine(value)Source

Write a string of characters to the file, following them with a new line character.

Parameters

1. value The value to write to the file.

Throws

• If the file has been closed.

WriteHandle.flush()Source

Save the current file without closing it.

Throws

• If the file has been closed.

WriteHandle.close()Source

Close this file, freeing any resources it uses.

Once a file is closed it may no longer be read or written to.

Throws

• If the file has already been closed.

BinaryWriteHandle

A file handle opened by fs.open using the "wb" or "ab" modes.

BinaryWriteHandle.write(...)Source

Write a string or byte to the file.

Parameters

1. charcode number The byte to write.

Or

1. contents string The string to write.

Throws

• If the file has been closed.

Changes

• Changed in version 1.80pr1: Now accepts a string to write multiple bytes.

BinaryWriteHandle.flush()Source

Save the current file without closing it.

Throws

• If the file has been closed.

BinaryWriteHandle.seek([whence [, offset]])Source

Seek to a new position within the file, changing where bytes are written to. The new position is an offset given by offset, relative to a start position determined by whence:

• "set": offset is relative to the beginning of the file.
• "cur": Relative to the current position. This is the default.
• "end": Relative to the end of the file.

In case of success, seek returns the new file position from the beginning of the file.

Parameters

1. whence? string Where the offset is relative to.
2. offset? number The offset to seek to.

Returns

1. number The new position.

Or

1. nil If seeking failed.
2. string The reason seeking failed.

Throws

• If the file has been closed.

Changes

• New in version 1.80pr1.9

BinaryWriteHandle.close()Source

Close this file, freeing any resources it uses.

Once a file is closed it may no longer be read or written to.

Throws

• If the file has already been closed.