Whatever message this page gives is out now! Go check it out!

DirectoryList

Last update:
May 18, 2026

Description

Lists the contents of on-disk or in-memory directory. Also lists the contents of the sub-directories if recurse is set to true.

Returns

Contents of the directory based on the parameter listInfo:
  • If listInfo="query", query object
  • If listInfo="name", array of names
  • If listInfo="path", array of path
Category
System functions

Function Syntax

DirectoryList(path [,recurse] [,listInfo] [,filter] [,sort] [,type] )

See Also

DirectoryCreate, DirectoryDelete, DirectoryExists, DirectoryRename

History

  • ColdFusion (2025 release): The filter callback for the directoryList function has been enhanced to return the data for the row it is filtering. You can filter the files returned from the DirectoryList function on the following attributes:
    • path
    • type
    • extension
    • attributes
    • lastmodifieddate
    • parent
    • link
    • name
    • size
The attributes are available as struct keys. The function also accepts a struct of the keys.
  • ColdFusion (2018 release): Introduced named parameters.
  • ColdFusion 11: Added the type argument.

Parameters

Parameter
Description
path
The absolute path of the directory for which to list the contents. Alternatively, you can specify IP address as in the following example: DirectoryList("//12.3.123.123/c_drive/test");.
recurse
Whether ColdFusion performs the action on subdirectories: If true, contents of all subdirectories are also listed.
listInfo
  • name: returns an array of names of files and directories.
  • path: returns an array of paths of files and directories.
  • query: returns a query.
filter
File extension filter applied to returned names, for example, *.cfm. Multiple filters can be applied by using a pipe delimiter. For example: *.beer|*.cookies
Also, you can pass a function in the filter argument:
<cfscript> 

boolean function filterBySize(path, type, extension) {
var sizeLimit = 1024 * 100; //more than 10 KB
var extensionList = "jpg,jpeg,gif,png";
if(type is "dir") return false;

if(listFindNoCase(extensionList,extension)) {
var fileInfo = getFileInfo(path);
var size = fileInfo.size;
if(size >= sizeLimit) return true;
}
return false;
}

filteredResults = directorylist(expandPath("."), true, "path", filterBySize);
writeDump(filteredResults);
</cfscript>
The arguments of the passed functions must have:
  • path: The file path
  • type: The values (file or dir )
  • extension: The file extension if any otherwise an empty string
 Additionally, it can also accept the instances of Java FileFilter Objects.
sort
Query columns by which to sort a directory listing. Delimited list of columns from query output.To qualify a column, use one of the following values:
  • asc: ascending (a to z) sort order.
  • dec: descending (z to a) sort order. For example:sort = "directory ASC, size DESC, datelastmodified"
type
  • file: includes only filenames.
  • dir: includes only directory names.
  • all: includes both filenames and directory names.

Usage

Ensure that you have the required permissions to run this function.
Example 1- See all files in the directory as an array
<cfscript>
    localFiles = directoryList( expandPath( "./" ), false, "name" )
    writeDump(localFiles)
</cfscript>
Example 2- Sort all files by last modified date and return a query
<cfscript>
    queryOfFiles = directoryList( expandPath( "./" ), false, "query", "", "DateLastModified DESC" );
    writeDump(queryOfFiles)
</cfscript>
Example 3- filter by path
application.cfc
component { 
    this.name ="ListDirectoryFilter" 
    void function onApplicationStart(){ 
    if( FindNoCase(server.os.name,"mac os x") OR FindNoCase(server.os.name,"unix")){ 
                application.slash="/"; 
            } 
    else{ 
                application.slash="\"; 
            } 
 
    } 

}
path.cfm
<cfscript> 
        boolean function filterByParent (fileFilter) { 
        var nameList = expandPath(".")&application.slash&"folder"; 
        if(listFindNoCase(nameList,fileFilter.parent)) return true; 
        return false; 
    } 

    filteredResults = directorylist(expandPath("."), true, "name", filterByParent); 
    writeDump(filteredResults) 
</cfscript>
Example 4- filter by type
<cfscript> 
    boolean function filterByTypeDir(fileFilter) { 
        if(fileFilter.type is "dir") return true; 
        else return false; 
    } 
    filteredResults = directorylist(expandPath("./.."), true, "name", filterByTypeDir, "extension asc", "dir"); 
    writeDump(filteredResults) 
</cfscript>
Example 5- filter by extension
<cfscript> 
    boolean function filterBySize (fileFilter) { 
        var extensionList = "cfm"; 
        if(fileFilter.extension is extensionList) return true; 
        else return false; 

    } 
    filteredResults = directorylist(expandPath("."), true, "name", filterBySize, "fileFilter.name DESC","all"); 
    writeDump(filteredResults) 
</cfscript>
Example 6- filter by attribute
<cfscript> 
    boolean function filterByAttributes (fileFilter) { 
        var attribList = "RH,R"; 
        if(listFindNoCase(attribList,fileFilter.attributes)) return true; 
        else return false; 
    } 
    filteredResults = directorylist(expandPath("./.."), true, "name", FilterByAttributes); 
    writeDump(filteredResults) 
</cfscript>
Example 7- filter by lastmodifieddate
<cfscript> 
    boolean function filterByDate (fileFilter) { 
        if(DateDiff("s",fileFilter.lastmodifieddate,now())>1) 
        {  
                return true; 
        } 
        else return false; 
    } 
    filteredResults = directorylist(expandPath("."), true, "name", filterByDate); 
    writeDump(filteredResults) 
</cfscript>
Example 8- filter by name
<cfscript> 
    boolean function filterByName (fileFilter) { 
        var nameList = "ReadOnly.txt,directorylist.cfm"; 
        if(ListContains(nameList,fileFilter.name)) return true; 
        return false; 

    } 
    filteredResults = directorylist(expandPath("."), true, "name", filterByName); 
    writeDump(filteredResults) 
</cfscript>
Example 9- filter by size
<cfscript> 
    // Verify list Directory returns appropriate results when name size is used 
    boolean function filterBySize (fileFilter) { 
        if(fileFilter.size>100) 
        {  
                return true; 
        } 
        return false; 
    } 

    filteredResults = directorylist(expandPath("."), true, "name", filterBySize); 
    writeDump(filteredResults) 
</cfscript>

Share this page

Was this page helpful?
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Thank you for your feedback. Your response will help improve this page.

On this page