FilesRename

Web-safe filenames: rules, tools & automation

This guide explains why web-safe filenames matter, how to clean them, and how to automate the process with our API.

Why filenames matter for the web

Recommended pattern

We recommend lowercase + underscores + ASCII-only, preserving the extension. Examples:


"Report Q4 – Métricas 2025.pdf"  →  "report_q4_metricas_2025.pdf"
"Longer Leisure Walking Time is Associated.pdf" → "longer_leisure_walking_time_is_associated.pdf"

Batch rename on Windows & macOS

Windows (PowerShell)


# rename all PDFs in the current folder to lowercase underscores (rough demo)
Get-ChildItem *.pdf | ForEach-Object {
  $n = $_.BaseName.ToLower() -replace '[^a-z0-9]+','_' -replace '_+','_'
  if ($n -eq '') { $n = 'file' }
  Rename-Item $_ -NewName "$n$($_.Extension.ToLower())"
}

macOS (Terminal)


for f in *.pdf; do
  base=$(basename "$f" .pdf)
  # naive transliteration; for accents use iconv
  clean=$(echo "$base" | iconv -f UTF-8 -t ASCII//TRANSLIT 2>/dev/null | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/_/g; s/_+/_/g; s/^_+|_+$//g')
  [ -z "$clean" ] && clean=file
  mv "$f" "${clean}.pdf"
done

Use the FilesRename API

POST /api/rename with multipart/form-data (files[]) to get a JSON response:


{
  "files": [
    {"original":"Longer Leisure Walking Time is Associated.pdf",
     "renamed":"longer_leisure_walking_time_is_associated.pdf",
     "url":"(stream-only mode returns the file directly)",
     "size": 315400, "mime": "application/pdf"}
  ]
}

Prefer a no-storage flow? Use POST /api/rename-stream.php — it streams the renamed file back without keeping a copy.

Best practices & tips