# Replacing Files and Naming Assets

> Source: https://agilitycms.com/docs/editors/replacing-files-and-naming-assets

This article covers how to replace a file in **Assets** so that every page and content item that uses it shows the new version, and which characters you can use in the name of a file you upload.

## Replace a file in place

To replace a file, upload the new file with exactly the same name, into the same folder.

1. Go to **Assets** and open the folder that holds the file you want to replace.
2. Click **Upload** and add the new file. Its file name must match the existing file's name.
3. Click **Upload**. Agility finds that a file with that name is already in the folder, and the dialog changes to **This file already exists** (or **Some files already exist** if you added several files).
4. Click **Replace** to overwrite the existing file with the new one, or **Skip** to keep the existing file.

A file with the same name in a *different* folder is a different file. Uploading there adds a new file and leaves the original alone.

## What happens when you replace a file

- **The URL stays the same.** Every page, component and content item that uses the file shows the new version. You don't need to edit or republish them.
- **The new file is live straight away.** Assets have no draft or publish step. See [Assets go live when you upload them](/docs/editors/introduction-to-assets#liveOnUpH2).
- **Agility clears the CDN cache for that file**, so the CDN serves the new version right away. A browser that already downloaded the old file may keep showing its saved copy until that copy expires. A hard refresh in the browser loads the new file.

Before you replace a file, check where it's used. See [Finding Where an Asset Is Used](/docs/editors/finding-where-an-asset-is-used).

If you want to keep the old file (to switch back to it, or because the change should wait for a launch), upload the new file under a different name instead, and point your content at it when you're ready.

## Characters you can use in file names

Agility won't upload a file whose name contains:

- Characters outside the basic English (ASCII) character set, such as accented letters, non-Latin scripts and emoji.
- Any of these characters: `#` `$` `&` `?` `%`

If you add a file like this, the upload dialog shows **Some files contain characters in their name that are not URL-safe and won't be uploaded.** The other files still upload. Rename the file on your computer and upload it again.

All other characters are allowed, including spaces, capital letters, hyphens, underscores, brackets and dots. By default Agility keeps the file name exactly as you uploaded it.

File names become part of the file's URL, so names made of lowercase letters, numbers and hyphens (for example `team-photo-2026.jpg`) give the cleanest URLs.

### Convert Uploaded Media Files to Lower Case

An administrator can turn on **Convert Uploaded Media Files to Lower Case** in [Global Configuration](/docs/owners-admins/global-configuration). When it's on, Agility changes the name of each file as you upload it:

- Spaces become hyphens.
- Any character other than a letter, number, hyphen, underscore or dot is removed.
- The name is converted to lowercase.

For example, `Team Photo (2026).JPG` is saved as `team-photo-2026.jpg`. The setting only affects new uploads. Files already in Assets keep their names.

When you replace a file with this setting on, Agility compares the converted name, so `Logo.PNG` replaces an existing `logo.png` in the same folder.

## Renaming a file

You can also rename a file in **Assets**. Renaming can break existing links to the file, so check where it's used first. See [Finding Where an Asset Is Used](/docs/editors/finding-where-an-asset-is-used#see-where-any-other-file-is-used).

## Related articles

- [Introduction to Assets](/docs/editors/introduction-to-assets)
- [Adding an Asset](/docs/editors/adding-an-asset)
- [Finding Where an Asset Is Used](/docs/editors/finding-where-an-asset-is-used)
- [Editing Images](/docs/editors/editing-images)

---

## Related pages

- [Introduction to Assets](https://agilitycms.com/docs/editors/introduction-to-assets.md)
- [Editing Images](https://agilitycms.com/docs/editors/editing-images.md)
- [Galleries](https://agilitycms.com/docs/editors/galleries.md)
- [Transforming Images with Query Strings and Focal Point](https://agilitycms.com/docs/editors/transforming-images-using-query-strings.md)
- [Finding Where an Asset Is Used](https://agilitycms.com/docs/editors/finding-where-an-asset-is-used.md)

Index of every docs page: https://agilitycms.com/docs/llms.txt