Naming Files Well

Last updated on 2026-07-31 | Edit this page

Overview

Questions

  • What makes a good filename?
  • How much information should be included in a filename?
  • Why are naming conventions important?
  • How can filenames support batch processing and automation?
  • How can I rename one file or many files using a graphical file browser?

Objectives

By the end of this episode, learners will be able to:

  • Identify problems with poorly named files.
  • Explain the characteristics of a good filename.
  • Choose an appropriate file naming convention.
  • Use filenames to support sorting and batch processing.
  • Rename an individual file using a graphical file browser.
  • Rename multiple files using bulk rename tools.
  • Apply a consistent naming convention to an existing dataset.

From Folder Names to File Names

In the previous episode, we improved the folder structure of the inherited project. However, fixing the folders has not solved all of our problems.

Consider the files we have been given:

Data!@#$.csv
Untitled.csv
copy of DSCO1023.png
03_04_26_results.csv
results-new.csv
data_final.xlsx
data_final_v2.xlsx
data_final_v3_LAST_ONE.xlsx

At best, these names are unhelpful. At worst, they actively prevent us from understanding the project or keeping track of progress, particularly when looking back on the work done months later.

Callout

Imagine receiving an email that says:

“Can you update the analysis using the latest data?”

Which file would you use?

data_final_final.xlsx
data_final_final_last_one.xlsx
data_final_final_last_one_test.xlsx
data_final_v21.xlsx
data_final_v2a.xlsx
data_final_v4_revised_jerrys_comments.xlsx

The answer is not obvious.

You do not want to resort to sorting the files by date and hoping that the last created or modified file was the last good file!

Good filenames should give us insight into what a file contains without needing to open it. Your choice of filenames should make subsequent analysis steps as frictionless as possible. If you find you are fighting your files in order to make progress in your work, there is probably something that can be improved. You have to be able to find your data in order to use it!

Your choice of filenames becomes increasingly important as projects grow larger, data is shared between collaborators, or data needs revisiting at a later date.

Discussion

Working in pairs, look through the files in the inherited project. What problems can you identify?

Consider:

  • Can you tell what the file contains?
  • Can you identify the newest version?
  • Are dates presented consistently?
  • Would the names be easy to process automatically?
  • Are there any confusing abbreviations?

Write down as many issues as you can find.

After a few minutes, discuss observations as a group.

Callout

Common issues with file names include

  • Meaningless names (data.csv)
  • Overly long names (1Nov16_polymer_test1_heating_123degree_measure14_userabc_id12345.txt)
  • Special characters (image#1.png)
  • Multiple date formats (23-Nov2024.csv, 2024-15-07.txt)
  • Ambiguous version information (data1bfinalfinal2reallyfinalusethis.txt)
  • Inconsistent separators (10-12_2019-data_ver1.img.csv) - although different separators can be used to split different types of information (e.g., 10-12-2019_data_ver1_img.csv consistently uses - to separate the date elements and _ to separate other text)
  • Difficult to parse names due to lack of separators (test1userabsnovember17.h5)
  • Duplicate information (24Nov_image01_241117.dat)

Why Filenames Matter

A filename serves several purposes simultaneously.

It helps answer

  • What is this file?
  • When was it created?
  • Which sample or dataset does it belong to?
  • Which version is this?
  • Can it be grouped with related files?

Good filenames support

  • Human understanding
  • Sharing and collaboration
  • Automated processing
  • Reproducibility

A filename should be easily useable by both a human reader and a computer. Keep in mind that humans and computers are good at different things and that different software and operating systems (Windows, macOS, Linux) have different conventions. Your filenames should be as portable as possible.

Future-you is one of the most important users of your naming convention, but it should also be easily understandable by colleagues.

Renaming a Single File

Now that we understand good naming principles, we need practical ways to apply them.

Discussion

Rename an example file

In our inherited dataset, find

Data!@#$.csv

A more descriptive name might be

2026-04-03_incidence_data_v01.csv

We can rename it via:

Characteristics of Good Filenames

Callout

There is no universal naming convention.

It is impossible to build an understandable, concise, informative template that accounts for all possible scenarios. Different projects require different information. However, successful file naming schemes usually share several characteristics.

Filenames should be

  • Meaningful
  • Consistent
  • Machine-friendly
  • Sortable
  • Clear

Meaningful

A filename should describe the contents of the file, for example:

The ‘good’ example immediately communicates useful information about the data: it measures the water quality at siteA on the 3rd April 2026. This name can be used by a human to easily find the desired data in a folder containing many files and reference it in code or documentation. For a computer, this filename information can help software load and sort the data without opening the document and reading its content. The ‘poor’ filename communicates almost nothing.

Consistent

Choose a convention and use it across all files.

Even if the files contain the same information, inconsistent naming makes them harder to understand and automatically analyse. If the folder contains many files, how would you be able to find a specific piece of data? For automation, the good filenames each contain the data’s date and sample id, allowing a script to easily loop through and find each file.

Machine-Friendly

Computers prefer predictable patterns.

Recommended characters:

  • letters
  • numbers
  • hyphens (-)
  • underscores (_)

Avoid:

- special characters: \ / : * ? " < > |
- spaces

These characters can have special meanings on different operating systems. Hyphens can cause issues because different word processors can substitute different characters which look almost the same. Similarly, word processors can autocorrect lower case letters into uppercase characters at the start of lines.

Caution

Unlike Linux and macOS file names, Windows file names are case insensitive. This difference can cause data loss when copying files from Linux or macOS to Windows file systems.

Sortable

Since files are usually displayed alphanumerically, choose file names that logically order your files.

Using ISO date format (YYYY-MM-DD) means the files will be grouped from first to last date. This organisation is more useful than sorting by day first, then month within that day, which instead sorts files by the day of the month:

01-02-2025_recording.csv
01-03-2025_recording.csv
01-05-2024_recording.csv
01-05-2023_recording.csv

which is usually, but not always, less useful.

When planning your file names, consider how alphabetical sorting will arrange your files. Place the most important metadata for grouping files (such as the date, subject, country, or sample) at the start of the file name.

Discussion

Ordering your files

Consider the metadata you collect for one of your projects. What metadata would you put first in your filenames to help sort your data files?

Clear

Filenames should be easily understood by humans and computers.

Separators provides breaks for the eye and for parsing using software.

What Information Should Go In a Filename?

Many researchers face a common temptation:

If information is useful, why not put all of it in the filename?

This can lead to names such as:

2026-06-01_12-43-16_sampling_trip_siteA_temperature_sensor_03_processed_final_v2.csv

which becomes difficult to read, particularly in a long list of files with similar names. Additionally, some operating systems and applications limit the allowed length of filenames and file paths.

Acronyms can make the file name smaller, but you don’t want to rely on a set of definitions taped to your office wall to remember them!

A useful guideline is:

Include enough information to identify the file, but not so much that the filename becomes documentation.

The most useful information might include:

  • date
  • sample identifier
  • location
  • experiment identifier
  • version

For example:

2026-06-01_siteA_sample03_v01.csv

Additional details can either be stored elsewhere:

  • README files
  • metadata files
  • data dictionaries
  • laboratory notebooks

or as a header or metadata in the file itself. Additionally, avoiding storing metadata only in the filename, as that information will be lost if the filename is inadvertently changed.

We will discuss documentation in the next episode.

Naming Files for Batch Processing

Consistent filenames allows files to be easily be processed together.

The files in the good example can be processed together by software and scripts, while files in the poor example are much harder to work with systematically.

When files may belong to a sequence, also use consistent numbering with leading zeros:

Leading zeros preserves the numeric order:

Callout

Remember to use enough digits for the expected total number of files. For example, if you expect 99 files or fewer, pad with one zero to format numbers as 01, 02,... 99. If you may have 100 to 999 files, use 001, 002,... 999.

Discussion

Choosing the number of digits

Consider the different types of files you create for one of your projects. Which files might be part of a larger sequence? How many files do you expect in each sequence, and how many digits should you include in the filenames for each one?

Bulk Renaming Files

Renaming one file is easy, but renaming hundreds is not.

Imagine receiving

IMG_001.png
IMG_002.png
IMG_003.png
...
IMG_125.png

from a collaborator.

Renaming each file individually would be extremely time consuming (and boring!).Fortunately, many operating systems provide ways to rename multiple files simultaneously.

For example:

IMG_001.png
IMG_002.png
IMG_003.png

might become:

siteA_image_01.jpg
siteA_image_02.jpg
siteA_image_03.jpg

Tools for bulk renaming:

All of these tools support replacing text as well as adding prefixes, suffixes, and numbering across multiple files simultaneously.

Challenge

Bulk renaming

Using a bulk rename tool, replace

IMG

with

siteA_image_
Challenge

Challenge

What could go wrong if a bulk rename operation is performed incorrectly?

How could you reduce risk?

  • Test on copies first.
  • Rename a small sample initially.
  • Keep backups.
  • Check the preview before applying changes.

Using Hierarchies Effectively

Remember that your folder hierarchy already provides information.

Suppose we have:

project/
└── case_studies/
    ├── scotland/
    ├── england/
    └── wales/

Inside each folder:

2026-06-01_image_01.png

is sufficient.

Avoid naming files:

scotland_2026-06-01_image_01.png

For example:

The location information is already present in the folder structure and so is redundant in the file name.

This example illustrates how each project has different filename requirements. If the ‘country’ layer of the directory structure wasn’t present, it would be useful to put the country in the filename. However, if you move files, the folder names would need to change; for example

scotland/2026-06-01_image_01.png
england/2026-07-01_image_01.png

would need to be renamed if placed in the same folder to avoid data loss.

Callout

Good folder structures and good filenames should work together.

Versioning Files

New versions of files can arise from repeated experiments, fresh downloads of data, and documentation or report edits. For some types of changes, you’ll want to keep non-destructive revisions to documents or an audit trail of changes. Versioning files keeps track of these changes over time, allowing you to manage different versions of files without overwriting previous ones.

Due to a lack of a versioning strategy, many researchers create filenames that making tracking revisions difficult:

The bad example is difficult to follow, while the good example uses explicit versions.

Avoid:

  • latest
  • final
  • newest
  • final_final
  • use_this_version

because these labels eventually become inaccurate. As soon as you edit report_final_final.docx it is no longer final (or even final final!), and you probably won’t go back to rename the earlier versions.

Callout

Various software tools can help with versioning without using multiple files. For example:

  • git for code, documents, and small files (commonly used via GitHub)
  • Microsoft Office (version history tools)
  • OneDrive
Challenge

Rename the inherited files

Working individually or in pairs:

Review the filenames in the inherited dataset and apply the principles discussed in this lesson.

Consider:

  • Meaningful descriptions
  • Consistent formatting
  • ISO dates where appropriate
  • Explicit version numbers
  • Removal of unnecessary special characters

Rename the files using File Explorer/Finder.

If a bulk rename tool is available, use it where appropriate.

There is no single correct answer.

A reasonable outcome might be

or

These different options are all good provided the convention is applied consistently throughout the project.

Looking Ahead

We have improved both the folder structure and the filenames.

However, many questions remain unanswered:

  • Where did the data come from?
  • How was it collected?
  • What do variables mean?
  • Which files should be used?

This information belongs in documentation.

In the next episode we will explore how README files, metadata, file headers, and provenance information make datasets understandable and reusable.

Key Points

Key Points

  • Good filenames help both people and computers understand data.
  • Consistency is more important than choosing a particular naming convention.
  • Use meaningful names that describe file contents.
  • Avoid spaces and special characters where possible.
  • Use ISO dates (YYYY-MM-DD) when dates are needed.
  • Include version numbers rather than labels such as “final” or “latest”.
  • Folder structures and filenames should work together.
  • Bulk renaming tools make large-scale renaming practical.
  • A filename should help identify a file without needing to open it.