os.listdir() Function Explained

os.listdir() gives you the names of files and folders inside a directory.

It is a useful function when you want to:

  • see what is inside a folder
  • loop through files
  • build file paths for later work
  • check directory contents before opening files

Quick example

import os

items = os.listdir('.')
print(items)

This lists the names of files and folders in the current directory.

What os.listdir() does

os.listdir() returns the names inside a directory.

Key points:

  • It usually returns a list of strings
  • It includes both files and folders
  • It does not tell you which names are files and which are directories by itself

So if a folder contains these entries:

  • notes.txt
  • images
  • script.py

then os.listdir() may return:

['notes.txt', 'images', 'script.py']

If you need to check what each name represents, you can combine os.listdir() with functions like os.path.join() and os.path.isfile().

Basic syntax

os.listdir(path='.')

How it works

  • path is the folder you want to inspect
  • If you do not give a path, Python uses the current working directory
  • You can pass a folder path as a string
  • The returned values are names only, not full paths

Example:

import os

print(os.listdir())
print(os.listdir('.'))

Both examples list the current working directory.

If you are not sure what your current working directory is, see os.getcwd() explained.

Simple example

Here is a basic example that lists the current directory:

import os

items = os.listdir('.')
print(items)

Possible output:

['main.py', 'data', 'notes.txt']

Important note about order

Do not rely on the order of the returned items.

The order is not guaranteed, so this might also happen:

['notes.txt', 'main.py', 'data']

If you want a stable order, use sorted():

import os

items = sorted(os.listdir('.'))
print(items)

List another directory

You can pass a different folder path to os.listdir().

Using a relative path

import os

items = os.listdir('data')
print(items)

This lists the contents of a folder named data relative to your current working directory.

Using an absolute path

import os

items = os.listdir('/Users/name/project/data')
print(items)

An absolute path is useful when the folder is outside your current location.

If your folder is not being found, the problem is often the path. It helps to check the current working directory with os.getcwd() and confirm the folder exists with os.path.exists().

Important return value details

os.listdir() returns directory entry names.

That means:

  • it returns names only
  • it does not return file contents
  • the names can be files, folders, or other entries
  • the order is not guaranteed

Example:

import os

items = os.listdir('.')

for name in items:
    print(name)

This prints names like:

main.py
data
notes.txt

If you want predictable output, sort the result first:

import os

for name in sorted(os.listdir('.')):
    print(name)

How to get full paths

Because os.listdir() returns names only, you often need to build full paths before doing more work.

Use os.path.join() for that:

import os

folder = 'data'

for name in os.listdir(folder):
    full_path = os.path.join(folder, name)
    print(full_path)

Possible output:

data/report.csv
data/image.png
data/archive

This is helpful before:

  • opening files
  • checking whether something is a file or folder
  • passing the path to another function

For more detail, see os.path.join() explained.

How to tell files from folders

os.listdir() does not separate files and folders for you.

To check each item, first build the full path, then use os.path.isfile() or os.path.isdir().

Example

import os

folder = 'data'

for name in os.listdir(folder):
    full_path = os.path.join(folder, name)

    if os.path.isfile(full_path):
        print(f"{name} is a file")
    elif os.path.isdir(full_path):
        print(f"{name} is a directory")

This is the safest pattern for beginners:

  1. get the name from os.listdir()
  2. build the full path
  3. check the path type

If your goal is specifically to list only files, see How to list files in a directory in Python.

Common errors and problems

A few common problems come up when using os.listdir().

FileNotFoundError

This happens when the path does not exist.

Example:

import os

print(os.listdir('missing_folder'))

If missing_folder is not real, Python raises an error.

Fixes:

  • make sure the folder exists
  • check the spelling
  • confirm you are using the correct relative path
  • print os.getcwd() to see where Python is looking

Related help: FileNotFoundError in Python: causes and fixes

PermissionError

This happens when Python cannot access the folder.

Example:

import os

print(os.listdir('/restricted_folder'))

Fixes:

  • use a folder your program can access
  • check file system permissions
  • avoid protected system locations unless needed

Related help: PermissionError in Python: causes and fixes

Relative path confusion

A path like 'data' only works if Python is running from the right place.

This command helps you check:

import os
print(os.getcwd())

If needed, use an absolute path or adjust your working directory.

Hidden files

Some systems include hidden files in directory listings.

So you may see names you were not expecting, such as files starting with . on Unix-like systems.

os.listdir() vs os.scandir()

os.listdir() is a simple choice when you only need names.

Use it when:

  • you want a quick list of entries
  • you are learning basic file handling
  • you do not need extra information right away

os.scandir() gives more information about each entry, such as methods to check whether it is a file or directory more directly.

For many beginner tasks, os.listdir() is easier to understand first.

If you want a broader view of file and directory tools, see the Python os module overview.

Common mistakes

These are the most common beginner mistakes with os.listdir():

  • Using a path that does not exist
  • Expecting full paths instead of names only
  • Assuming the result contains only files
  • Assuming the order will always be the same
  • Using a relative path from the wrong working directory

Useful debugging checks:

import os
print(os.getcwd())

import os
print(os.listdir('.'))

import os
print(os.path.exists('your_folder'))

import os
print(os.path.isdir('your_folder'))

These checks help you answer:

  • Where is Python running from?
  • Does the folder exist?
  • Is the path really a directory?
  • What does the current directory contain?

FAQ

Does os.listdir() return files only?

No. It returns names of both files and directories.

Does os.listdir() return full file paths?

No. It returns names only. Use os.path.join() to build full paths.

Can I use os.listdir() without a path?

Yes. It will list the current working directory.

Why is my folder not being found?

You may be using the wrong relative path. Check os.getcwd() and confirm the folder exists.

How do I sort the results?

Wrap the result with sorted(), for example:

import os

print(sorted(os.listdir('.')))

See also