Introduction

tf.data.Dataset.list_files() creates a dataset whose elements are file paths, not file contents. That means the filenames are already there as scalar string tensors; the main task is understanding how to inspect them, decode them, or carry them forward through your input pipeline.

Core Sections

What list_files Returns

At a high level, list_files turns a glob pattern into a dataset of path strings.

1import tensorflow as tf
2
3files = tf.data.Dataset.list_files("/tmp/images/*.jpg", shuffle=False)
4
5for path in files.take(3):
6    print(path)

Typical output looks like a TensorFlow string tensor:

tf.Tensor(b'/tmp/images/cat.jpg', shape=(), dtype=string)

So the filename is not hidden. It is the dataset element itself.

Access Filenames in Eager Execution

If you are running in eager mode, convert each tensor to a Python string with .numpy(), then decode it.

1import tensorflow as tf
2
3files = tf.data.Dataset.list_files("/tmp/images/*.jpg", shuffle=False)
4
5for path in files.take(3):
6    print(path.numpy().decode("utf-8"))

That is the easiest way to inspect filenames during debugging or exploratory work.

You can also materialize the dataset with as_numpy_iterator():

for raw_path in files.take(3).as_numpy_iterator():
    print(raw_path.decode("utf-8"))

Use the Filename Inside a Pipeline

A common pattern is to read the file content while still keeping the path available for labels, logging, or output naming.

1import tensorflow as tf
2
3files = tf.data.Dataset.list_files("/tmp/images/*.jpg", shuffle=False)
4
5def load_with_path(path):
6    image_bytes = tf.io.read_file(path)
7    image = tf.image.decode_jpeg(image_bytes, channels=3)
8    image = tf.image.resize(image, [128, 128])
9    return path, image
10
11dataset = files.map(load_with_path)
12
13for path, image in dataset.take(1):
14    print(path.numpy().decode("utf-8"))
15    print(image.shape)

Returning both values is often better than discarding the path immediately. It gives you traceability later in the pipeline.

Extract Just the Base Filename

If you only want cat.jpg instead of the full path, use TensorFlow string operations so the logic stays inside the graph-friendly pipeline.

1import tensorflow as tf
2
3files = tf.data.Dataset.list_files("/tmp/images/*.jpg", shuffle=False)
4
5def base_name(path):
6    return tf.strings.split(path, "/")[-1]
7
8for name in files.map(base_name).take(3):
9    print(name.numpy().decode("utf-8"))

For cross-platform code, tf.strings.regex_replace or preprocessing outside the pipeline may be safer than assuming a slash separator everywhere.

Build Labels From Filenames

Sometimes the filename itself contains the class label or identifier. You can derive labels directly from the path.

1import tensorflow as tf
2
3files = tf.data.Dataset.list_files("/tmp/data/*/*.jpg", shuffle=False)
4
5def extract_label(path):
6    parts = tf.strings.split(path, "/")
7    return parts[-2]
8
9dataset = files.map(lambda path: (path, extract_label(path)))
10
11for path, label in dataset.take(2):
12    print(path.numpy().decode("utf-8"), "->", label.numpy().decode("utf-8"))

That pattern is common when directory names represent classes, such as cats/, dogs/, or cars/.

Another useful pattern is to keep the path all the way through batching so failed predictions can be traced back to source files later. That is especially helpful in evaluation code, dataset audits, and export jobs that need deterministic filename-to-output mapping.

That path-carrying approach also makes it much easier to log bad samples, copy specific files for manual review, or generate reports that join model outputs back to original filenames without rebuilding the dataset from scratch.

Common Pitfalls

• Expecting list_files to yield file contents instead of path tensors.
• Using normal Python string methods inside a TensorFlow map function.
• Forgetting that list_files shuffles by default unless you set shuffle=False.
• Converting tensors to Python strings too early in a production input pipeline.
• Dropping the path immediately even though later stages need filenames for labels, logging, or exports.

Summary

• 'tf.data.Dataset.list_files() produces a dataset of filename tensors.'
• In eager mode, use .numpy().decode("utf-8") or as_numpy_iterator() to inspect paths.
• Keep the path in the pipeline if you need traceability, labels, or output naming.
• Use TensorFlow string operations inside map functions instead of Python string methods.
• Set shuffle=False when deterministic filename order matters.