File Naming Conventions & Limits
File naming conventions vary dramatically across operating systems, cloud storage services, and web platforms. What works on macOS might fail on Windows. What uploads fine to Dropbox might break on AWS S3. This reference covers maximum path lengths, filename limits, forbidden characters, and case sensitivity rules — plus best practices for cross-platform compatibility.
When You Need This Table
- Sharing files between Windows, macOS, and Linux systems
- Uploading assets to cloud storage or CDNs
- Creating file naming standards for your team or organization
- Debugging "file not found" errors caused by naming issues
- Building applications that handle user-uploaded files
Platform Limits
| Platform | Max Path | Max Filename | Forbidden Chars | Case Sensitive |
|---|---|---|---|---|
| Windows | 260 | 255 | \ / : * ? " < > | | No |
| macOS | 1024 | 255 | / : | Varies* |
| Linux | 4096 | 255 | / NUL | Yes |
| Web URLs | 2048 | N/A | spaces, #, %, &, ? | Usually |
| AWS S3 | 1024 | N/A | None (but avoid special chars) | Yes |
| Google Drive | N/A | 255 | \ / : * ? " < > | | No |
| Dropbox | N/A | 255 | / \ | No |
*macOS: APFS is case-sensitive by default on some volumes; HFS+ is case-insensitive.
Naming Best Practices
| File Type | Example | Notes |
|---|---|---|
| General files | quarterly-report-2025-q1.pdf | Use hyphens, lowercase, date suffixes |
| Images (web) | hero-banner-homepage.webp | Descriptive, SEO-friendly, web format |
| Versioned docs | contract-v2.1-signed.pdf | Include version numbers |
| Code files | userAuthService.ts | camelCase or kebab-case per language convention |
| Backup files | db-backup-2025-01-15.sql | ISO date format (YYYY-MM-DD) |
Universal Rules
- Use lowercase letters and hyphens for cross-platform compatibility
- Avoid spaces — use hyphens or underscores instead
- Keep file names under 50 characters when possible
- Put dates in ISO format (YYYY-MM-DD) for proper sorting
Web & SEO Considerations
- Use descriptive names for images (helps SEO)
- Replace spaces with hyphens in URLs
- Avoid special characters that need URL encoding
- Keep image filenames relevant to content
Cross-Platform File Naming Strategy
The safest approach for cross-platform compatibility is to follow the most restrictive rules: use lowercase letters, numbers, hyphens, and underscores only. Avoid spaces entirely — they cause issues in URLs, command-line operations, and some cloud storage systems.
Windows has the most forbidden characters (9 special characters can't be used) and historically had a 260-character path limit, though this can now be extended. Linux is more permissive but case-sensitive, meaning "Report.pdf" and "report.pdf" are different files — a common source of bugs.
For web development, descriptive filenames matter for SEO. "hero-banner-summer-sale.webp" helps search engines understand your image content, while "IMG_1234.jpg" provides no context. Use our Text to Slug tool to convert titles into URL-safe filenames.
Common Pitfalls to Avoid in File Naming
One of the most frequent errors is mixing case-sensitive and case-insensitive systems. For example, a file named 'Report.pdf' and 'report.pdf' might be treated as separate files in Linux but will conflict in Windows. This can cause data overwrites or confusion in version control. Another common mistake is using spaces or unsupported characters like '#' or '@' in web URLs, which can break links or require unnecessary encoding. Developers should also avoid relying on platform-specific conventions when creating cross-platform tools—always validate filenames against the strictest rules (e.g., Windows' forbidden characters). Finally, inconsistent date formats (like using '2025-01-15' versus '01-15-2025') can lead to sorting issues in file systems, especially in automated workflows.
Web-Specific File Naming Best Practices
For websites and web applications, file naming affects SEO, performance, and maintainability. Use kebab-case (e.g., 'hero-banner-homepage.jpg') instead of camelCase or snake_case for URLs, as search engines prefer hyphens for readability. Avoid excessive length—keep filenames under 50 characters to ensure URL compatibility and prevent truncation in UIs. Image files should include descriptive keywords (e.g., 'product-organic-coffee-beans.jpg' instead of 'img_1234.jpg') to improve accessibility and search rankings. When using static site generators or CDNs, test filenames for edge cases like special characters in build pipelines. Always include version numbers or timestamps in asset filenames (e.g., 'style-20250315.css') to bypass browser caching issues during deployments.
Avoiding Common Naming Pitfalls
Even with knowledge of system limits, many users still run into issues due to subtle naming pitfalls. For example, using leading or trailing spaces in filenames can cause silent failures—especially when scripts or APIs trim whitespace unexpectedly. Similarly, filenames that differ only in case (e.g., ‘Report.pdf’ vs ‘report.pdf’) may work fine on macOS or Linux during development but break when deployed to case-sensitive servers like those used in many CI/CD pipelines. Another frequent issue is relying on Unicode characters beyond basic ASCII; while modern OSes often support them, legacy systems, FTP clients, or URL encoders may misinterpret or reject them entirely. Always test critical filenames across target platforms before finalising workflows, especially when files will be shared externally or used in automated processes.
Choosing Between camelCase, snake_case, and kebab-case
The choice of word separator in filenames—camelCase, snake_case, or kebab-case—depends heavily on context and ecosystem conventions. camelCase (e.g., userAuthService.ts) is standard in JavaScript/TypeScript codebases and some IDEs, while snake_case (e.g., user_auth_service.py) dominates in Python, R, and many database contexts. kebab-case (e.g., user-auth-service.css) is preferred for web assets (HTML, CSS, URLs) because it’s URL-safe and avoids issues with shell escaping or legacy tools that interpret underscores differently. For maximum compatibility, avoid spaces and special characters entirely. When in doubt, kebab-case is the safest choice for public-facing or cross-platform files. Consistency within a project matters more than the specific style, so establish and document your team’s convention early.
Automating Naming Compliance
Manually enforcing file naming standards across teams is error-prone. Consider integrating automated checks into your workflow: pre-commit hooks (e.g., using Husky or lint-staged) can reject commits with non-compliant filenames; CI pipelines can run scripts to validate filenames against your rules before deployment. Tools like rename, find, or custom Node.js/Python scripts can batch-rename files to meet standards. For cloud uploads, services like AWS S3 or Google Cloud Storage offer SDKs with built-in validation or sanitisation utilities. Some IDEs (e.g., VS Code) support workspace-specific settings or extensions that warn about or auto-correct problematic names. Establishing these checks early prevents costly fixes later—especially when integrating with third-party tools that assume strict naming conventions.