Renamly docs

Renamly ships as a standard WordPress plugin. It requires WordPress 6.0+ and PHP 7.4+ (PHP 8.1+ recommended). WooCommerce is optional — Renamly detects it automatically and lights up product-aware features when it's present.

Install

• Download the Renamly ZIP from your purchase receipt or the free listing.
• In WordPress, open Plugins → Add New → Upload Plugin and pick the ZIP.
• Click Activate. Renamly appears in the sidebar under Media → Renamly.
• Open Renamly → License and paste your Pro key to unlock bulk mode, AI, redirects, WP-CLI and auto-attach.

First rename

Head to Media → Renamly Dashboard. Every media entry appears with its current filename, the proposed new filename, and a Rename Nowbutton. Try a single rename first, confirm it looks right in your posts, then run a bulk pass with confidence.

A naming method is the rule Renamly uses to decide what a file should be called. Pick one as your default in Renamly → Settings → Naming.

• Product-aware (WooCommerce). Uses the title of the product the image is attached to. Best for stores.
• Attached-post title. Uses the title of any post/page/CPT the image is attached to.
• Media title. Uses the media entry's own Title field. Best when your team already curates titles.
• AI vision. Describes the image using your Anthropic or OpenAI key, then slugs the description.
• Numbered. Uses a stable stem plus an auto-incrementing counter (e.g. image-0142.jpg).
• Anonymized. Replaces filenames with random hashes. Useful for private-media sites where filenames leak intent.

What Renamly cleans up

• Lowercases the extension and normalizes it (JPEG → jpg).
• Removes diacritics (café → cafe) and non-URL-safe characters.
• Collapses whitespace and separators into single hyphens.
• Trims leading/trailing separators and dots.
• Enforces a max length so long product titles don't create broken paths on Windows/IIS hosts.

Real libraries are messy — some images are attached to products, some to posts, some to nothing. Cascading lets you chain naming methods with automatic fallback, so every file gets the best available name.

In Settings → Naming → Cascade, drag methods into priority order. Renamly walks the list top-down and uses the first one that produces a valid result:

1. Product-aware       → attached to a WooCommerce product? use it
2. Attached-post title → attached to any post/CPT? use its title
3. AI vision           → key configured? describe and name
4. Numbered            → last resort, never fails

Renamly can rename on three events: new upload, media title change, and — for WooCommerce — product title change. Toggle each independently.

Rename on save

If you edit media titles from inside the post editor, Renamly can't rename immediately without breaking the images you're currently referencing. With Rename on save enabled, Renamly queues the change and applies it when the post is saved, drafted, scheduled or published — links get rewritten in the same transaction, so the post keeps rendering.

With this option off, queued renames wait for you in the Renamly dashboard. Click Rename Now to apply them one at a time.

Renaming a file is only half the job. Renamly rewrites every reference to the old filename in the same operation, across:

• Post and page content (post_content).
• All registered thumbnail sizes on disk and in _wp_attachment_metadata.
• Widget content, customizer options, and page-builder JSON payloads that store URLs as strings.
• http://, https:// and protocol-relative //example.com URLs.
• The image's own attachment guid, so REST responses stay consistent.

301 redirects (Pro)

Pro writes a permanent 301 from every old file URL to its new one. External sites, Google image results and cached emails keep working. Redirects live in a lightweight table Renamly manages — no .htaccess edits — and are automatically cleaned up when you undo a rename.

A file rename is a good moment to keep the media's textual metadata in sync. Renamly can optionally update the media entry's Title, ALT text, Caption and Description whenever it renames a file — one consistent story per image, great for SEO and screen readers.

• ALT text is stored in the media entry's meta. Inline alt="" attributes already baked into old post HTML are not modified — the browser reads them from the media entry anyway when the image is rendered by WordPress.
• Title mirrors the human-friendly version of the new filename (spaces, capitalization).
• Caption / Description are opt-in. Off by default so you don't overwrite curated copy.

Use the renamly_rewrite_alt filter to append your brand name, product SKU, or any string. See Filters below.

Undo

Every rename is logged with the old filename, new filename, timestamp, user and method. One click restores the previous filename and reverses every reference rewrite Renamly made in the same operation — including the 301 redirect.

Lock

Lock any file to permanently exclude it from auto-rename, bulk runs, and title sync. Locked files still appear in the dashboard, marked with a so you know why they're being skipped.

Status filters

The dashboard filters media into four groups so you can prioritize work:

• Never renamed — original filename, no history.
• Pending — proposed new filename differs from current, queued for rename.
• Renamed — current filename matches the naming rule.
• Locked — user has explicitly opted out.

Bulk mode is designed for libraries with thousands of files on shared hosts with 30-second PHP timeouts. Renamly processes media in small, checkpointed batches over AJAX — safe to close the tab and resume later. The runner picks up exactly where it left off.

Tips for very large libraries

• Run a Preview pass first — Renamly shows every proposed change without touching files.
• Disable Update References temporarily if you only need file renames and will handle URL updates separately (or via 301s).
• On very slow hosts, raise max_execution_time and PHP memory. Renamly still batches, but bigger batches finish faster.
• Use WP-CLI for the initial migration — it bypasses PHP-FPM timeouts entirely.

Renamly reads three signals to decide which product an image belongs to, in this priority order:

• Featured image on the product.
• Product gallery images.
• WordPress attachment relationship (post_parent).

Variant naming

For variation images, Renamly appends the variant attributes automatically — e.g. -black-large — so every SKU has a uniquely named image. Optional: append the SKU too ( -SKU123) via a single toggle.

Auto-attach

Orphan product images — sitting in the media library with no post_parent — are common after CSV imports and page-builder work. Auto-attach scans them and suggests a product based on:

• SKU match anywhere in the filename.
• Product slug match (fuzzy).
• AI-vision description matched against product titles (Pro + AI key).

Review the suggestions queue and accept them one at a time, or bulk-accept when the confidence score is above a threshold you pick.

Renamly does not bundle an AI key or proxy your images through our servers. You bring your own Anthropic or OpenAI key, paste it in Settings → AI, and Renamly calls the provider directly from your WordPress site with your billing.

What gets sent

• The image binary (or its URL if the provider fetches).
• A short system prompt asking for a concise, filename-friendly description.
• Nothing else. No post content, no order data, no customer PII.

Supported providers & models

• OpenAI: gpt-4o, gpt-4o-mini, gpt-4.1-mini (vision-capable models).
• Anthropic: claude-3.5-sonnet, claude-3-haiku.
• Local: any OpenAI-compatible endpoint (Ollama, LM Studio) via the Custom endpoint field.

Renamly ships WP-CLI commands for migrations, staging refreshes and CI. All commands respect your dashboard settings unless overridden by a flag.

# rename a single media entry
wp renamly rename 4821

# rename everything, small batches, resume-safe
wp renamly bulk --batch=50

# preview only — no changes on disk or in DB
wp renamly bulk --dry-run

# auto-attach orphan product images (WooCommerce)
wp renamly attach --min-confidence=0.8

# undo the last N renames
wp renamly undo --limit=100

# rebuild the 301 redirect table from the history log
wp renamly redirects rebuild

By default only administrators (users with manage_options) can access the Renamly dashboard and its settings. Override with two filters:

// let editors use the Renamly dashboard
add_filter( 'renamly_allow_usage', function ( $allow ) {
  return current_user_can( 'editor' ) || $allow;
} );

// let a custom capability access the settings
add_filter( 'renamly_allow_setup', function ( $allow ) {
  return current_user_can( 'manage_renamly' ) || $allow;
} );

Renamly exposes a small, stable API of filters and actions. All are prefixed with renamly_.

Customize the generated filename

Prepend the upload date to every name:

add_filter( 'renamly_new_filename', function ( $new, $old, $media ) {
  $date = date( 'Y-m-d', strtotime( $media['post_date'] ) );
  return $date . '-' . $new;
}, 10, 3 );

Pro adds a variant that also receives the attached post — handy for stores that want the product slug baked in even when using a different naming method:

add_filter( 'renamly_new_filename_attached', function ( $new, $old, $media, $attached ) {
  return $new . '-' . sanitize_title( $attached['post_title'] );
}, 10, 4 );

Character-level replacement rules

add_filter( 'renamly_replace_rules', function ( $rules ) {
  $rules['ß'] = 'ss';
  $rules['&'] = 'and';
  return $rules;
} );

Rewrite the ALT text on rename

add_filter( 'renamly_rewrite_alt', function ( $alt, $media ) {
  return trim( $alt . ' – ' . get_bloginfo( 'name' ) );
}, 10, 2 );

Whitelist / blacklist specific media

add_filter( 'renamly_allow_rename', function ( $allow, $media, $proposed ) {
  // never rename files in a specific folder
  if ( strpos( $media['file'], 'do-not-touch/' ) === 0 ) {
    return false;
  }
  return $allow;
}, 10, 3 );

React to a completed rename

add_action( 'renamly_path_renamed', function ( $media_id, $old_path, $new_path ) {
  // register a redirect, ping a CDN, log to Slack, etc.
}, 10, 3 );

add_action( 'renamly_url_renamed', function ( $media_id, $old_url, $new_url ) {
  // sync references in a page builder that stores URLs oddly
}, 10, 3 );

If a third-party importer creates posts or uploads media programmatically, WordPress often doesn't fire the events Renamly listens to. Trigger a rename yourself once your import finishes:

// after your importer finishes uploading:
foreach ( $imported_media_ids as $id ) {
  renamly_rename( $id );
}

Useful WordPress action hooks to piggyback on:

• add_attachment — a new media entry is created.
• attachment_updated — a media entry's fields change.
• woocommerce_update_product — a WooCommerce product is saved.
• publish_post, post_updated — a post is published or updated.

Renamly transliterates accented characters and non-Latin scripts into clean ASCII slugs (Café → cafe, Токио → tokio). This keeps URLs readable everywhere, avoids CDN edge cases, and eliminates a whole class of encoding bugs on shared hosts.

Case-sensitivity

Linux and modern macOS filesystems are case-sensitive: Cat.JPG and cat.jpg are two different files. Windows and some managed hosts are case-insensitive, so copying Cat.JPG over cat.jpg silently overwrites it. Enable Case-insensitive checks in Settings if you're on Windows/IIS — small performance cost, big safety win. Leave it off on standard Linux hosts.

Migrated hosts and UTF-8 encoding

If you moved WordPress between hosts and see broken accented filenames, the DB and the filesystem probably disagree on encoding. Fix: re-upload /wp-content/uploads/ from the source host via FTP with UTF-8 enforced. Renamly can then take over cleanly.

"Why didn't this file get renamed?"

• The ideal filename already exists on disk. Enable Numbering to append a counter (-2, -3, …).
• The current filename ends in a counter (image-2.jpg). Renamly leaves these alone to avoid collisions — rename them manually if needed.
• The file is locked. Unlock it from the dashboard.
• The media has no title, no attached post/product, and no AI key. Add one, or enable the Numbered fallback in the cascade.

"My site is broken after a rename"

• Clear all caches first — browser, hosting cache, CDN, and any page-cache plugin. Nine times out of ten, the site is fine and cached URLs are stale.
• Use the Undo button on the offending rename in the dashboard history.
• If a page builder stores URLs in a serialized/encoded blob, its images will look broken even though the file was renamed correctly. Rely on 301 redirects (Pro), or hook renamly_url_renamed to patch that builder's storage yourself.
• As a last resort, restore your latest backup and open a support ticket with the details — we'll help you narrow it down.

Timeouts on very large libraries

• Reduce the bulk batch size to 25 or 10.
• Turn off Update References for the initial file rename pass and re-run with it on afterwards.
• Increase PHP max_execution_time and memory limits.
• Move to WP-CLI for the initial pass — it doesn't hit PHP-FPM timeouts.

Grayed-out filename field

Manual filename editing requires Pro and the Manual Renaming setting toggled on in Renamly → Settings.

Enable debug logs

Turn on Debug logging in Settings. Renamly writes to a rolling log at /wp-content/uploads/renamly-logs/ — include the latest log with any support ticket.