← All articles

File naming conventions explained (and why yours are probably bad)

The 6 rules every file naming convention should follow, with real-world examples from teams that get it right.

· 9 min read

You probably have a “file naming convention.” It probably exists in your head, half-applied, with three exceptions you’ve forgotten. That’s most people. The good news: a real convention is six rules long and you can adopt one this afternoon.

Why naming matters more than folders

A solid argument from the systems-thinking world: filenames are the only metadata that survives. Move a file across operating systems, sync it to a cloud, ZIP it, attach it to an email — folders, tags, permissions all get stripped. The filename stays.

That means the filename is doing two jobs: it’s a label and an index. A file called final_v2_REAL.docx fails at both. A file called 2026-04-19_lisbon-proposal_v03.docx succeeds at both.

The 6 rules

1. ISO 8601 dates at the start

YYYY-MM-DD. Always. Never 04-19-2026 (American), never 19-04-2026 (European), never Apr 19 2026 (text).

Why: when files are sorted alphabetically, ISO dates also sort chronologically. 2026-04-19_x.txt comes before 2026-04-20_y.txt automatically. No tool needed.

✓ 2026-04-19_invoice.pdf
✗ 19-04-2026_invoice.pdf
✗ April-19-2026_invoice.pdf

2. Lowercase only

Case-sensitivity is a real trap. macOS is case-insensitive by default; Linux and Git are case-sensitive. A team where some people commit Logo.png and others reference logo.png will eventually have a “file not found” bug in production.

Side benefit: lowercase looks calmer and is faster to type.

✓ tokyo-2026-001.jpg
✗ Tokyo-2026-001.JPG

3. No spaces, no special characters

Use - (hyphens) or _ (underscores). Avoid é, &, #, ?, /, \, :, *. They:

  • Break URLs (a ? in a filename means “query string” to a browser)
  • Break shell commands (spaces split arguments)
  • Break tab-completion in terminals
  • Get URL-encoded into ugly %20%C3%A9 mess
✓ rapport-trimestriel_v02.pdf
✗ Rapport Trimestriel (Final)?.pdf

4. Underscore vs hyphen: pick one role for each

The convention used by Wikipedia, GitHub Pages, and most pros:

  • Hyphen (-) separates words within a logical unit: tokyo-2026, client-onboarding.
  • Underscore (_) separates logical units: 2026-04-19_tokyo-2026_001.jpg.

This way a filename parses cleanly: date_event_counter.ext. You can split on underscore in any script in 1 line.

5. Versioning with leading zeros

v01, v02, …, v10, v11. Not v1, v2, …, v10 (which sorts as v1, v10, v11, v2).

Same with counters: 001, 002, …, 999. Even if you don’t expect to hit 100, you’ll be glad later.

✓ contract_v01.pdf, contract_v02.pdf, contract_v10.pdf
✗ contract_v1.pdf, contract_v10.pdf, contract_v2.pdf

6. Descriptive but compact

The Goldilocks rule: 30-60 characters. Long enough to be self-explanatory, short enough not to wrap in your file browser.

✓ 2026-04-19_lisbon-proposal_v03.pdf
✗ proposal.pdf                                              (too vague)
✗ 2026-04-19_complete-final-revised-proposal-document-for-the-lisbon-acme-corp-project-version-3-real-final.pdf  (too long)

Putting it together

The general formula:

[date]_[project-or-context]_[descriptor]_[version].ext

Examples:

Use caseFilename
Wedding photo2026-04-26_smith-wedding_001.jpg
Invoice2026-04-19_acme_invoice-042.pdf
Design draft2026-05-02_app-redesign_homepage_v04.fig
Meeting notes2026-05-02_q2-planning_notes.md
Product imagewidget-blue_001.jpg (no date — atemporal)

Notice the last one breaks the date rule. That’s fine: rules exist to serve clarity, not the other way around. Catalog/inventory files where the date doesn’t matter (a product photo doesn’t expire) can skip it.

How to apply this to existing files

You probably have thousands of files that don’t follow these rules. Two options:

Option A: only enforce going forward

The 80/20 move. Adopt the convention for new files, leave old ones alone unless they’re causing pain. Most files older than a year you’ll never touch again anyway.

Option B: bulk-rename the important ones

For client-facing folders, project archives, or anything you’ll search frequently: use a batch renamer to apply the convention in one pass. Drop the folder, set prefix + numbering + lowercase + remove specials, export. 312 files become consistent in 30 seconds.

Don’t try to retrofit your entire 20-year file history. It’s not worth it.

Real conventions from real teams

A few examples I’ve collected from teams that get this right:

Newsroom:

2026-04-19_byline-renault_topic-renaming_v02.docx

Date for sortability, byline for ownership, topic for searchability.

E-commerce (1000s of SKUs):

sku-12345_main.jpg
sku-12345_back.jpg
sku-12345_detail-01.jpg

SKU first (catalog-driven), shot type as suffix. Date irrelevant — products don’t have a “date.”

Code project assets:

icon-search-24.svg
icon-search-32.svg

Component name + size. No date, no version — Git tracks history.

Photography portfolio:

2026_paris_001.jpg
2026_paris_002.jpg

Year + location + counter. No month/day for archival shots.

The pattern: adapt the formula to your domain, but stay consistent within it.

What about emojis and Unicode?

Tempting. Don’t.

Emojis break terminal display, file syncing, ZIP extraction, and email attachments. Unicode characters beyond ASCII break older Windows tools. Stick to [a-z0-9_-] and you’re guaranteed compatibility everywhere.

If you really need to flag certain files visually, use a folder name or a prefix like _priority_ or 00_.

TL;DR

  • ISO dates first. Lowercase only. Hyphens within units, underscores between units.
  • Leading zeros on counters and versions.
  • 30-60 character filenames. Self-explanatory but not novelistic.
  • Apply to new files; bulk-rename old ones with a batch tool if needed.
  • Adapt the formula to your domain — but be consistent within it.

Pick one folder this week. Rename it according to the rules. Notice how much faster you find things. Then expand from there.