For those who don’t know what LFS is, it’s a popular Lua library which allows you to perform common file system activities that can’t normally be done in plain Lua. Things like getting file attributes, creating and removing directories (folders), and iterating over files in a directory are all things that can be easily done using LFS.

For this tutorial, it might help to have a separate window open with the LFS Reference.

Directory scanning

Imagine that you are creating a note-taking app that allows users to create, save, and read text-based notes that are all saved to system.DocumentsDirectory. Sure, it’s easy to keep track of what the user does inside of your app — you can simply keep your own record of the notes within a “notes” table and update it whenever something is added or removed from the app’s documents directory.

But what if you want to implement file sharing so that users can import and export notes? This is where LuaFileSystem would be extremely useful. Every time your app is launched, you can use LFS to scan the contents of system.DocumentsDirectory and “check” for new notes. You can do this as much as you need to ensure that you have an accurate account of exactly what is inside that folder. Of course, this is just one example where you might use this functionality — as with everything, it all boils down to the individual needs of your app.

Here’s an example of how to iterate over the contents of the app’s documents directory using a simple for loop:

local lfs = require( "lfs" )

local doc_path = system.pathForFile( "", system.DocumentsDirectory )

for file in lfs.dir( doc_path ) do
    -- File is the current file or directory name
    print( "Found file: " .. file )

Adding folders

If your app downloads several external assets and you would like to organize different types of files into different folders (or you are working with lots of files with similar file names), being able to add and remove folders is absolutely essential. Fortunately, LFS makes this task easy. First, you’ll need to change the “current directory” to where you want to place the folder using lfs.chdir() and then use lfs.mkdir() to actually create the directory.

local lfs = require( "lfs" )

-- Get raw path to app's temporary directory
local temp_path = system.pathForFile( "", system.TemporaryDirectory )

-- Change current working directory
local success = lfs.chdir( temp_path )  -- Returns true on success
local new_folder_path

if success then
    lfs.mkdir( "MyNewFolder" )
    new_folder_path = lfs.currentdir() .. "/MyNewFolder"

Deleting folders

If you need to remove (delete) a directory, it is recommended you use the existing os.remove() function to do so. While lfs.rmdir() can only remove directories, os.remove() can handle both.


In some cases, you may need to periodically check the “last modified” timestamp of certain files, especially if you’re implementing any kind of syncing functionality, or even simply keeping track of when the user last loaded a specific file (but didn’t necessarily change it).

Setting a new timestamp

Let’s say we have a file called mydata.txt inside of system.TemporaryDirectory. Imagine that the user wants to view the file, but we want to set the timestamp for when the user last read the file (not just the last time they wrote to it). In this case, we would simply “touch” the file. In doing so, we set the “last modified” timestamp to today/now. You can also set a custom “access time” and “modification time” with two additional function arguments, or leave them blank to use the current time.

local lfs = require( "lfs" )

local file_path = system.pathForFile( "mydata.txt", system.TemporaryDirectory )

-- "Touch" the file
lfs.touch( file_path )

Retrieving an existing timestamp

At some point later, let’s find out when the file was last modified. For this, we can either use the “access” or “modification” property:

local lfs = require( "lfs" )

local file_path = system.pathForFile( "mydata.txt", system.TemporaryDirectory )

-- Get last modified time
local file_attr = lfs.attributes( file_path )
local last_mod = file_attr.modification

print( last_mod )


LuaFileSystem is very powerful and it can do more things than what is illustrated here. Fortunately, most of the LFS functions are straightforward and easy to use. Please see the LFS reference page for a complete listing of available functions and syntax information for each one.

  1. Ha! I was just looking for a way to scan directories and ended up logging each file downloaded so I knew what was in the Docs directory. If only this came 3 weeks earlier…

  2. Seems like this won’t work for any files in the ResourceDirectory…..

    For example, if you want to build an inventory (table) of image assets, then
    system.pathForFile( “”, system.ResourceDirectory )
    will return nil, rather than a starting directory (which LFS requires as a string).

    Do we have an api to get a path to a directory in Resources (rather than docs/temp)??
    I can just temporarily copy my images to Docs unless anyone else has found a way around this??

  3. Thanks for sharing this Jonathan. I’m wondering if I can use this on Android to allow a user to add (manually) mp3 files to the document directory, and to play them with Corona.

    My need is to allow an Android user to play an mp3 of his choice (not pre-installed with the app). On iOS I can use the iTunes plugin to play external mp3, but it’s not available on Android. So I’m looking for another way.

    My plan B was to ask the Android users to copy their mp3 in the document directory of the app. But I cannot see where the document directory of my Corona app is…

    Any idea?

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>