Tutorial: LuaFileSystem (LFS)

Share on Facebook0Share on Google+1Tweet about this on TwitterShare on LinkedIn0

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:

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.

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.

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:


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.

Share on Facebook0Share on Google+1Tweet about this on TwitterShare on LinkedIn0

Brent Sorrentino serves as a full-time Developer Evangelist for Corona Labs, assisting developers in the forums, maintaining documentation/guides, and creating samples which highlight core features of Corona SDK.

This entry has 10 replies

  1. Satheesh says:

    Whew! Finally!
    Thanks guys!

  2. Nenad Katic says:

    This is awesome, thanks ! 🙂

  3. KennWags says:

    Great and much needed – thanks!

  4. Willy Joseph says:

    This is really great! Great work, keep it coming!

  5. Simon says:

    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…

  6. sunil says:

    so this capability has always been there through use of os.execute – admittedly this wraps it up nicely.

    see use of lfs to write an on device debug log file.


  7. Hendrix says:

    This is real nice (the api calls remind me of the old DOS days LOL) nice and easy put guys

  8. Dewey says:

    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??

  9. 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?

  10. NoNameNPC says:

    Is it a way to use masks for example *.log i want to search thru all drive in search of files to delete them