Replace images or files in your Media Library while keeping the same URL, so updates apply everywhere the file is used.
You can replace images or files in your Media Library while keeping the URL the same. This allows you to globally replace an image everywhere it is used.
This feature requires the Image Editor, which is available on paid plans.
After editing an image, it may take up to 30 seconds to appear on your computer due to browser caching. Clear your browser cache to see the updated image immediately:
Browser
Shortcut
Windows browsers
CTRL + F5
Mac Safari
SHIFT + Reload button
Mac Chrome/Firefox
CMD + SHIFT + R
Was this page helpful?
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"ButterCMS Docs","colors":{"primary":"#0505e5","light":"#5050ff","dark":"#0000a0"},"logo":{"light":"https://cdn.buttercms.com/nDD3LeMXQxiR9aJRpRLE","dark":"https://cdn.buttercms.com/nDD3LeMXQxiR9aJRpRLE","href":"https://buttercms.com"},"favicon":"https://mintcdn.com/buttercms/ADHjuou5Js2KRBnv/favicon.svg?fit=max\u0026auto=format\u0026n=ADHjuou5Js2KRBnv\u0026q=85\u0026s=719e07eca4e3b3446e3ba6621a6095f0","navbar":{"links":[{"href":"https://buttercms.com/sales/","label":"Request a Demo"}],"primary":{"type":"button","label":"Start for Free","href":"https://app.buttercms.com/join/"}},"seo":{"metatags":{"canonical":"https://buttercms.com/docs","robots":"noindex, nofollow"}},"integrations":{"gtm":{"tagId":"GTM-W7DPCL97"}},"interaction":{"drilldown":true},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"buttercms","hasAudioNarration":false,"actualSubdomain":"buttercms","customDomains":["buttercms.com"],"gitSource":{"type":"github","owner":"buttercms","repo":"buttercms","deployBranch":"master","contentDirectory":"unified-docs","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true,"agentFeedback":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6af1f01fc512f821748a9f47","clientVersion":"0.0.4102","searchFilterCounts":[{"language":"default","tag":"Frameworks","count":79},{"language":"default","tag":"Build your app","count":74},{"language":"default","tag":"Create content","count":74},{"language":"default","tag":"API Reference","count":63},{"language":"default","tag":"Creating and editing content","count":24},{"language":"default","tag":"Core concepts","count":23},{"language":"default","tag":"Starter projects","count":21},{"language":"default","tag":"All starter projects","count":20},{"language":"default","tag":"Webhooks API","count":19},{"language":"default","tag":"How-to recipes","count":18}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"/docs","hasChatPermissions":false,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":".mermaid .node rect,.mermaid .node circle,.mermaid .node ellipse,.mermaid .node polygon{fill:#f0f4ff!important;stroke:#0505e5!important;stroke-width:2px!important}.mermaid .node .label,.mermaid .node text,.mermaid .nodeLabel{font-family:'Open Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif!important;fill:#000022!important;font-size:14px!important;font-weight:500!important}.mermaid .cluster rect{fill:#f8fafc!important;stroke:#5050ff!important;stroke-width:2px!important;rx:8px!important;ry:8px!important}.mermaid .cluster text,.mermaid .cluster .nodeLabel{fill:#0505e5!important;font-weight:600!important;font-size:15px!important}.mermaid .edgePath .path,.mermaid .flowchart-link{stroke:#5050ff!important;stroke-width:2px!important}.mermaid .arrowheadPath,.mermaid marker path{fill:#5050ff!important;stroke:#5050ff!important}.mermaid .edgeLabel,.mermaid .edgeLabel rect{background-color:#ffffff!important;fill:#ffffff!important}.mermaid .edgeLabel p,.mermaid .edgeLabel>p,.mermaid .edgeLabel div,.mermaid .edgeLabel>div{background:#f8fafc!important}.mermaid .edgeLabel text,.mermaid .edgeLabel .label{fill:#000022!important;font-size:12px!important}.mermaid .actor{fill:#f0f4ff!important;stroke:#0505e5!important;stroke-width:2px!important}.mermaid .actor-line{stroke:#5050ff!important;stroke-width:1px!important}.mermaid text.actor{fill:#000022!important;font-weight:600!important}.mermaid .messageText{fill:#000022!important;font-size:13px!important}.mermaid .messageLine0,.mermaid .messageLine1{stroke:#5050ff!important;stroke-width:1.5px!important}.mermaid .note{fill:#fbe700!important;stroke:#c4b800!important}.mermaid .noteText{fill:#000022!important}.mermaid .statediagram-state rect{fill:#f0f4ff!important;stroke:#0505e5!important;stroke-width:2px!important;rx:6px!important}.mermaid .state-start,.mermaid .state-end{fill:#0505e5!important}.mermaid .pieTitleText{fill:#0505e5!important;font-weight:600!important;font-size:16px!important}.mermaid .classGroup rect{fill:#f0f4ff!important;stroke:#0505e5!important}.mermaid .classGroup text{fill:#000022!important}.mermaid .er.entityBox{fill:#f0f4ff!important;stroke:#0505e5!important}.mermaid .section{fill:#f0f4ff!important}.mermaid .task{fill:#5050ff!important;stroke:#0505e5!important}.mermaid .taskText{fill:#ffffff!important}.mermaid,pre:has(.mermaid),div:has(>.mermaid){max-width:100%!important;min-width:100%!important;padding:1.5rem!important}.mermaid svg{width:100%!important;max-width:100%!important;height:auto!important;min-height:200px!important;max-height:800px!important}.dark .mermaid .edgeLabel p,.dark .mermaid .edgeLabel>p,.dark .mermaid .edgeLabel div,.dark .mermaid .edgeLabel>div{background:#1a1a2e!important}.dark .mermaid{background:#1a1a2e!important}.dark .mermaid .node rect,.dark .mermaid .node circle,.dark .mermaid .node ellipse{fill:#2a2a4a!important;stroke:#5050ff!important}.dark .mermaid .node text,.dark .mermaid .nodeLabel{fill:#e0e0e0!important}.dark .mermaid .cluster rect{fill:#1e1e3a!important;stroke:#5050ff!important}.dark .mermaid .cluster text{fill:#8080ff!important}.dark .mermaid .edgePath .path,.dark .mermaid .flowchart-link{stroke:#7070ff!important}.dark .mermaid .arrowheadPath{fill:#7070ff!important}.dark .mermaid .edgeLabel rect{fill:#1a1a2e!important}.dark .mermaid .edgeLabel text{fill:#e0e0e0!important}.diagram-modal-toggle{display:none}.diagram-container{position:relative}.diagram-preview{position:relative;display:block;cursor:zoom-in;transition:opacity 0.2s ease}.diagram-preview:hover{opacity:0.95}.diagram-expand-hint{position:absolute;top:12px;right:12px;background:rgba(255, 255, 255, 0.95);color:#0505e5;padding:6px 12px;border-radius:6px;font-size:12px;font-weight:500;opacity:0;transition:opacity 0.2s ease;pointer-events:none;box-shadow:0 2px 8px rgba(0, 0, 0, 0.15);z-index:10}.diagram-preview:hover .diagram-expand-hint{opacity:1}.dark .diagram-expand-hint{background:rgba(30, 30, 46, 0.95);color:#8080ff}.diagram-modal-overlay{position:fixed;top:0;left:0;right:0;bottom:0;background:rgba(0, 0, 0, 0.9);display:none;align-items:center;justify-content:center;z-index:9999;padding:2rem;cursor:zoom-out}.diagram-modal-toggle:checked~.diagram-modal-overlay{display:flex;animation:fadeIn 0.2s ease}.diagram-modal-content{max-width:90vw;max-height:90vh;background:#ffffff;border-radius:12px;padding:2rem;box-shadow:0 20px 60px rgba(0, 0, 0, 0.5);cursor:default;overflow:auto}.dark .diagram-modal-content{background:#1a1a2e}.diagram-modal-toggle:checked~*{overflow:hidden}.mermaid-lightbox-wrapper{position:relative;cursor:zoom-in;transition:all 0.2s ease}.mermaid-lightbox-wrapper:hover{opacity:0.95}.mermaid-expand-icon{position:absolute;top:12px;right:12px;width:32px;height:32px;display:flex;align-items:center;justify-content:center;background:rgba(255, 255, 255, 0.95);border-radius:6px;box-shadow:0 2px 8px rgba(0, 0, 0, 0.15);opacity:0;transition:opacity 0.2s ease, transform 0.2s ease;pointer-events:none;z-index:10}.mermaid-lightbox-wrapper:hover .mermaid-expand-icon{opacity:1;transform:scale(1.05)}.mermaid-expand-icon svg{width:18px;height:18px;color:#0505e5}.dark .mermaid-expand-icon{background:rgba(30, 30, 46, 0.95)}.dark .mermaid-expand-icon svg{color:#8080ff}.mermaid-lightbox-overlay{position:fixed;top:0;left:0;right:0;bottom:0;background:rgba(0, 0, 0, 0.9);display:flex;align-items:center;justify-content:center;z-index:9999;padding:2rem;animation:fadeIn 0.2s ease;cursor:zoom-out}@keyframes fadeIn{from{opacity:0}to{opacity:1}}.mermaid-lightbox-content{max-width:90vw;max-height:90vh;background:#ffffff;border-radius:12px;padding:2rem;box-shadow:0 20px 60px rgba(0, 0, 0, 0.5);cursor:default;overflow:auto}.dark .mermaid-lightbox-content{background:#1a1a2e}.mermaid-lightbox-content .mermaid{padding:0!important}.mermaid-lightbox-content .mermaid svg{max-height:85vh!important;width:auto!important;max-width:85vw!important}.mermaid-lightbox-close{position:fixed;top:1.5rem;right:1.5rem;width:48px;height:48px;display:flex;align-items:center;justify-content:center;background:rgba(255, 255, 255, 0.95);border:none;border-radius:50%;cursor:pointer;box-shadow:0 4px 12px rgba(0, 0, 0, 0.3);transition:all 0.2s ease;z-index:10000}.mermaid-lightbox-close:hover{transform:scale(1.1);background:#ffffff}.mermaid-lightbox-close svg{width:24px;height:24px;color:#000022}.dark .mermaid-lightbox-close{background:rgba(30, 30, 46, 0.95)}.dark .mermaid-lightbox-close:hover{background:#1e1e3a}.dark .mermaid-lightbox-close svg{color:#e0e0e0}.mermaid-scroll-zoom{overflow:auto;max-height:500px;border:1px solid #e5e7eb;border-radius:12px;background:#ffffff;margin:1rem 0;cursor:grab;position:relative}.mermaid-scroll-zoom:active{cursor:grabbing}.dark .mermaid-scroll-zoom{border-color:#374151;background:#1a1a2e}.mermaid-scroll-zoom .mermaid{padding:1.5rem!important;min-width:100%;width:max-content}.mermaid-scroll-zoom .mermaid svg{min-width:120%;max-width:none!important;max-height:none!important;height:auto!important;transform-origin:top left}.mermaid-zoom-hint{text-align:center;font-size:12px;color:#6b7280;margin:0.5rem 0 1rem 0;font-style:italic}.dark .mermaid-zoom-hint{color:#9ca3af}.mermaid-scroll-zoom::-webkit-scrollbar{width:8px;height:8px}.mermaid-scroll-zoom::-webkit-scrollbar-track{background:#f1f1f1;border-radius:4px}.mermaid-scroll-zoom::-webkit-scrollbar-thumb{background:#c1c1c1;border-radius:4px}.mermaid-scroll-zoom::-webkit-scrollbar-thumb:hover{background:#a1a1a1}.dark .mermaid-scroll-zoom::-webkit-scrollbar-track{background:#2a2a4a}.dark .mermaid-scroll-zoom::-webkit-scrollbar-thumb{background:#4a4a6a}.dark .mermaid-scroll-zoom::-webkit-scrollbar-thumb:hover{background:#5a5a7a}@media (max-width: 768px){.mermaid-lightbox-overlay{padding:1rem}.mermaid-lightbox-content{max-width:95vw;max-height:95vh;padding:1rem}.mermaid-lightbox-content .mermaid svg{max-height:90vh!important;max-width:90vw!important}.mermaid-lightbox-close{width:40px;height:40px;top:1rem;right:1rem}.mermaid-lightbox-close svg{width:20px;height:20px}.mermaid-expand-icon{opacity:0.8}}"}],"page":{"pagePath":"create-content/media-management/replacing-media-files","slug":"/create-content/media-management/replacing-media-files","pageMetadata":{"title":"Replacing media files","description":"Replace images or files in your Media Library while keeping the same URL, so updates apply everywhere the file is used.","icon":"arrow-right-arrow-left","href":"/create-content/media-management/replacing-media-files"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Replace images or files in your Media Library while keeping the same URL, so updates apply everywhere the file is used.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={img:`img`,li:`li`,ol:`ol`,p:`p`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{Heading,Info,Table}=_components;if(!Heading)_missingMdxReference(`Heading`,true);if(!Info)_missingMdxReference(`Info`,true);if(!Table)_missingMdxReference(`Table`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`You can replace images or files in your Media Library while keeping the URL the same. This allows you to globally replace an image everywhere it is used.`}),`\n`,_jsx(Info,{children:_jsx(_components.p,{children:`This feature requires the Image Editor, which is available on paid plans.`})}),`\n`,_jsx(Heading,{level:`3`,id:`how-to-replace-a-file`,children:`How to replace a file`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsx(_components.li,{children:`Search for the file that needs to be updated`}),`\n`,_jsxs(_components.li,{children:[`Click on the `,_jsx(_components.strong,{children:`Replace`}),` button`]}),`\n`]}),`\n`,_jsx(_components.p,{children:_jsx(_components.img,{src:`https://cdn.buttercms.com/REBYrJXTQyyUEcg1U51p`,alt:`Replace Button`})}),`\n`,_jsxs(_components.ol,{start:`3`,children:[`\n`,_jsxs(_components.li,{children:[`Select the new file you want to upload and click `,_jsx(_components.strong,{children:`Upload`})]}),`\n`]}),`\n`,_jsx(Heading,{level:`3`,id:`cache-clearing-note`,children:`Cache clearing note`}),`\n`,_jsx(_components.p,{children:`After editing an image, it may take up to 30 seconds to appear on your computer due to browser caching. Clear your browser cache to see the updated image immediately:`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Browser`}),_jsx(_components.th,{children:`Shortcut`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Windows browsers`})}),_jsx(_components.td,{children:`CTRL + F5`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Mac Safari`})}),_jsx(_components.td,{children:`SHIFT + Reload button`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Mac Chrome/Firefox`})}),_jsx(_components.td,{children:`CMD + SHIFT + R`})]})]})]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Replacing media files","description":"Replace images or files in your Media Library while keeping the same URL, so updates apply everywhere the file is used.","icon":"arrow-right-arrow-left","href":"/create-content/media-management/replacing-media-files"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"How to replace a file","slug":"how-to-replace-a-file","depth":3,"children":[]},{"title":"Cache clearing note","slug":"cache-clearing-note","depth":3,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"buttercms","siteName":"ButterCMS Docs","title":"Replacing media files - ButterCMS Docs","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-04-17T11:33:10.657Z","originalFileLocation":"create-content/media-management/replacing-media-files.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Replace images or files in your Media Library while keeping the same URL, so updates apply everywhere the file is used.\">\u003cmeta data-mint-head name=\"application-name\" content=\"ButterCMS Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003cmeta data-mint-head name=\"robots\" content=\"noindex, nofollow\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/buttercms/r9p2A1fiqo_BuZws/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/docs/mintlify-assets/_mintlify/favicons/buttercms/r9p2A1fiqo_BuZws/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/buttercms/r9p2A1fiqo_BuZws/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/buttercms/r9p2A1fiqo_BuZws/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/buttercms/r9p2A1fiqo_BuZws/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/buttercms/r9p2A1fiqo_BuZws/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/buttercms/r9p2A1fiqo_BuZws/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/buttercms/r9p2A1fiqo_BuZws/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/buttercms/r9p2A1fiqo_BuZws/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Replacing media files - ButterCMS Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Replace images or files in your Media Library while keeping the same URL, so updates apply everywhere the file is used.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"ButterCMS Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://buttercms.com/docs/create-content/media-management/replacing-media-files\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://buttercms.mintlify.site/docs/_mintlify/api/og/v2?division=The+media+library\u0026amp;title=Replacing+media+files\u0026amp;description=Replace+images+or+files+in+your+Media+Library+while+keeping+the+same+URL%2C+so+updates+apply+everywhere+the+file+is+used.\u0026amp;theme=5b7441fa906780c0ab866249\u0026amp;signature=be94ed6921abe265fbb2461391dd2f88f7bfca39b2629f453dc158a13b59e693\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Replacing media files - ButterCMS Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Replace images or files in your Media Library while keeping the same URL, so updates apply everywhere the file is used.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://buttercms.mintlify.site/docs/_mintlify/api/og/v2?division=The+media+library\u0026amp;title=Replacing+media+files\u0026amp;description=Replace+images+or+files+in+your+Media+Library+while+keeping+the+same+URL%2C+so+updates+apply+everywhere+the+file+is+used.\u0026amp;theme=5b7441fa906780c0ab866249\u0026amp;signature=be94ed6921abe265fbb2461391dd2f88f7bfca39b2629f453dc158a13b59e693\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/docs/mintlify-assets/_mintlify/favicons/buttercms/r9p2A1fiqo_BuZws/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"ButterCMS Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0505e5\">\u003clink data-mint-head rel=\"canonical\" href=\"https://buttercms.com/docs/create-content/media-management/replacing-media-files\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/docs/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/create-content/media-management/replacing-media-files.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://buttercms.com/#organization\",\"name\":\"ButterCMS Docs\",\"url\":\"https://buttercms.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://cdn.buttercms.com/nDD3LeMXQxiR9aJRpRLE\"}},{\"@type\":\"WebSite\",\"@id\":\"https://buttercms.com/docs#website\",\"name\":\"ButterCMS Docs\",\"url\":\"https://buttercms.com/docs\",\"publisher\":{\"@id\":\"https://buttercms.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://buttercms.com/docs/create-content/media-management/replacing-media-files#webpage\",\"url\":\"https://buttercms.com/docs/create-content/media-management/replacing-media-files\",\"name\":\"Replacing media files\",\"description\":\"Replace images or files in your Media Library while keeping the same URL, so updates apply everywhere the file is used.\",\"dateModified\":\"2026-04-17T11:33:10.657Z\",\"isPartOf\":{\"@id\":\"https://buttercms.com/docs#website\"},\"breadcrumb\":{\"@id\":\"https://buttercms.com/docs/create-content/media-management/replacing-media-files#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://buttercms.com/docs/create-content/media-management/replacing-media-files#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Managing media\",\"item\":\"https://buttercms.com/docs/create-content/media-management/media-library-overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"The media library\",\"item\":\"https://buttercms.com/docs/create-content/media-management/media-library-overview\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Replacing media files\",\"item\":\"https://buttercms.com/docs/create-content/media-management/replacing-media-files\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://buttercms.com/docs/create-content/media-management/replacing-media-files#article\",\"headline\":\"Replacing media files\",\"name\":\"Replacing media files\",\"description\":\"Replace images or files in your Media Library while keeping the same URL, so updates apply everywhere the file is used.\",\"url\":\"https://buttercms.com/docs/create-content/media-management/replacing-media-files\",\"mainEntityOfPage\":{\"@id\":\"https://buttercms.com/docs/create-content/media-management/replacing-media-files#webpage\"},\"dateModified\":\"2026-04-17T11:33:10.657Z\",\"publisher\":{\"@id\":\"https://buttercms.com/#organization\"},\"isPartOf\":{\"@id\":\"https://buttercms.com/docs#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"ButterCMS Docs\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"ButterCMS Docs\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/docs/create-content/media-management/replacing-media-files.md","siteName":"ButterCMS Docs","nav":{"global":null,"tabs":[{"tab":"Quickstart","pages":[{"title":"Quickstart","href":""}]},{"tab":"Core concepts","pages":[{"title":"Core concepts","href":"/core-concepts/content-types/overview"}]},{"tab":"Create content","groups":[{"group":"Overview","pages":[{"title":"Table of contents","icon":"book-open","href":"/create-content/overview"}]},{"group":"Guides and tutorials","pages":[{"title":"Find how-to recipes","icon":"hammer","href":"/create-content/how-to-recipes"}]},{"group":"Creating and editing content","pages":[{"group":"Dashboard essentials","icon":"gauge","pages":[{"title":"Dashboard overview \u0026 navigation","icon":"compass","href":"/create-content/creating-editing-content/dashboard-essentials/dashboard-overview"},{"title":"Accessing your content","icon":"folder-open","href":"/create-content/creating-editing-content/dashboard-essentials/accessing-content"},{"title":"Account and profile settings","icon":"user-gear","href":"/create-content/creating-editing-content/dashboard-essentials/account-settings"}]},{"group":"Add pages, collections, \u0026 blog posts","icon":"file-plus","pages":[{"title":"Creating pages","icon":"file-plus","href":"/create-content/creating-editing-content/add-pages-collections-posts/creating-pages"},{"title":"Creating Collection items","icon":"database","href":"/create-content/creating-editing-content/add-pages-collections-posts/creating-collections"},{"title":"Creating Blog Posts","icon":"newspaper","href":"/create-content/creating-editing-content/add-pages-collections-posts/creating-blog-posts"}]},{"group":"Fields basics","icon":"cogs","pages":[{"title":"Configuring and validating fields","icon":"gear","href":"/create-content/creating-editing-content/fields-basics/configuring-and-validating-fields"},{"title":"Adding default values to fields","icon":"sliders","href":"/create-content/creating-editing-content/fields-basics/default-field-values"},{"title":"Using the WYSIWYG editor","icon":"text","href":"/create-content/creating-editing-content/fields-basics/wysiwyg-editor"}]},{"group":"Reference fields","icon":"link","pages":[{"title":"Reference fields: overview","icon":"link","href":"/create-content/creating-editing-content/reference-fields/reference-fields-overview"},{"title":"Working with Reference fields","icon":"clipboard-list","href":"/create-content/creating-editing-content/reference-fields/working-with-reference-fields"}]},{"group":"Repeaters","icon":"rotate-right","pages":[{"title":"Understanding Repeaters","icon":"rotate-right","href":"/create-content/creating-editing-content/repeaters/understanding-repeaters"},{"title":"Creating Repeater fields","icon":"plus","href":"/create-content/creating-editing-content/repeaters/creating-repeater-fields"},{"title":"Managing Repeater items","icon":"list-check","href":"/create-content/creating-editing-content/repeaters/managing-repeater-items"}]},{"group":"Components","icon":"layer-group","pages":[{"title":"Components: overview","icon":"layer-group","href":"/create-content/creating-editing-content/components/components-overview"},{"title":"Create, use, and delete Components","icon":"hammer","href":"/create-content/creating-editing-content/components/creating-components"},{"title":"Component Library","icon":"warehouse","href":"/create-content/creating-editing-content/components/component-library-overview"},{"title":"The Component Picker","icon":"layer-plus","href":"/create-content/creating-editing-content/components/using-component-picker"},{"title":"Component versioning","icon":"code-branch","href":"/create-content/creating-editing-content/components/component-versioning"},{"title":"Conditional fields in Components","icon":"code-branch","href":"/create-content/creating-editing-content/components/conditional-fields-components"}]},{"group":"Forms","icon":"wpforms","pages":[{"title":"Overview","icon":"gauge","href":"/create-content/creating-editing-content/forms/forms-overview"},{"title":"Embedding forms in ButterCMS fields","icon":"code","href":"/create-content/creating-editing-content/forms/embedding-forms"},{"title":"Form integrations in the dashboard","icon":"plug","href":"/create-content/creating-editing-content/forms/form-integrations"},{"title":"Custom form modeling in dashboard","icon":"sliders","href":"/create-content/creating-editing-content/forms/custom-form-handling"}]}]},{"group":"Managing media","pages":[{"group":"The media library","icon":"photo-film","pages":[{"title":"Media Library overview","icon":"compass","href":"/create-content/media-management/media-library-overview"},{"title":"Uploading assets","icon":"cloud-arrow-up","href":"/create-content/media-management/uploading-assets"},{"title":"Adding media to content","icon":"image-circle-plus","href":"/create-content/media-management/adding-media"},{"title":"Finding media","icon":"magnifying-glass","href":"/create-content/media-management/finding-media"},{"title":"Organizing media","icon":"folder-tree","href":"/create-content/media-management/organizing-media"},{"title":"Bulk delete media","description":"Delete multiple media files at once from the Media Library to save time during cleanup.","icon":"trash","href":"/create-content/media-management/bulk-delete-media"},{"title":"Replacing media files","icon":"arrow-right-arrow-left","href":"/create-content/media-management/replacing-media-files"},{"title":"Adding alt text","description":"Add alt text to images in your ButterCMS Media Library to improve accessibility and SEO. Learn how to set alternative text and access it through the API.","icon":"universal-access","href":"/create-content/media-management/alt-text"},{"title":"Automatic image compression \u0026 WebP","icon":"bolt","href":"/create-content/media-management/automatic-image-compression-webp"},{"title":"Image editing and transformations","icon":"wand-magic-sparkles","href":"/create-content/media-management/image-editing-transformations"},{"title":"External integrations","icon":"plug","href":"/create-content/media-management/media-integrations"}]}]},{"group":"Publishing lifecycle","pages":[{"group":"Preview, schedule, publish, \u0026 delete","icon":"file-pen","pages":[{"title":"Content status: draft to published","icon":"circle-check","href":"/create-content/publishing-lifecycle/content-status"},{"title":"Managing drafts","icon":"file-pen","href":"/create-content/publishing-lifecycle/managing-drafts"},{"title":"Filtering pages by status","icon":"filter","href":"/create-content/publishing-lifecycle/filtering-by-status"},{"title":"Previewing changes in the dashboard","icon":"eye","href":"/create-content/publishing-lifecycle/previewing-changes"},{"title":"Scheduling content publication","icon":"calendar","href":"/create-content/publishing-lifecycle/scheduling-publication"},{"title":"Deleting content","icon":"trash","href":"/create-content/publishing-lifecycle/deleting-content"}]}]},{"group":"Versioning and history","pages":[{"group":"View, compare, and restore versions","icon":"clock-rotate-left","pages":[{"title":"Revision history overview","icon":"clock-rotate-left","href":"/create-content/versioning-history/revision-history-overview"},{"title":"Viewing previous versions","icon":"list","href":"/create-content/versioning-history/viewing-previous-versions"},{"title":"Restoring content","icon":"rotate-left","href":"/create-content/versioning-history/restoring-content"},{"title":"Retention policies","icon":"hourglass-half","href":"/create-content/versioning-history/retention-policies"}]}]},{"group":"Authentication","pages":[{"group":"Authentication methods","icon":"shield-halved","pages":[{"title":"Overview","icon":"compass","href":"/create-content/authentication/authentication-overview"},{"title":"Password authentication","icon":"lock","href":"/create-content/authentication/password-authentication"},{"title":"OAuth 2.0 login (Google \u0026 GitHub)","icon":"right-to-bracket","href":"/create-content/authentication/oauth-social-login"},{"title":"Single sign-on (SSO)","icon":"key","href":"/create-content/authentication/single-sign-on"},{"title":"Multi-factor authentication (MFA)","icon":"shield-halved","href":"/create-content/authentication/multi-factor-authentication"},{"title":"Heroku add-on","icon":"plug","href":"/create-content/authentication/heroku-add-on"},{"title":"API tokens","icon":"webhook","href":"/create-content/authentication/api-tokens"}]}]},{"group":"Collaborating with teams","pages":[{"group":"Collaboration features","icon":"comments","pages":[{"title":"Workflows","icon":"message","href":"/create-content/collaborating-with-teams/content-approval-workflows"},{"title":"Team presence","icon":"users","href":"/create-content/collaborating-with-teams/team-presence"},{"title":"Slack integration","icon":"slack","href":"/create-content/collaborating-with-teams/slack-integration"}]},{"group":"User management","icon":"users","pages":[{"title":"Team management","icon":"users-gear","href":"/create-content/collaborating-with-teams/team-management"}]},{"group":"Roles and permissions","icon":"user-shield","pages":[{"title":"Default roles: Admin, publisher, editor","icon":"user-group","href":"/create-content/collaborating-with-teams/default-roles"},{"title":"Custom roles and permissions","icon":"shield-halved","href":"/create-content/collaborating-with-teams/custom-roles-permissions"}]}]},{"group":"Localization","pages":[{"group":"Working with locales","icon":"globe","pages":[{"title":"Localizing content","icon":"rocket","href":"/create-content/localization/publishing-localized-content"},{"title":"Locale-based permissions","icon":"globe","href":"/create-content/localization/locale-based-permissions"}]},{"group":"Languages and translation","icon":"language","pages":[{"title":"Translating content","icon":"language","href":"/create-content/localization/translating-content"}]}]},{"group":"Multi-site and environments","pages":[{"group":"Working with multiple sites \u0026 environments","icon":"sitemap","pages":[{"title":"Multisite overview","icon":"sitemap","href":"/create-content/multi-site-environments/multisite-overview"},{"title":"Working with multisites","icon":"browsers","href":"/create-content/multi-site-environments/working-with-multisites"},{"title":"Migrating content","icon":"arrow-right-arrow-left","href":"/create-content/multi-site-environments/migrating-content"},{"title":"Multi-site user management","icon":"users","href":"/create-content/multi-site-environments/multi-site-user-management"}]}]},{"group":"SEO","pages":[{"group":"Optimizing SEO","icon":"search","pages":[{"title":"SEO and ButterCMS","icon":"magnifying-glass-chart","href":"/create-content/seo/seo-and-buttercms"},{"title":"SEO in Collections","icon":"database","href":"/create-content/seo/seo-in-collections"},{"title":"SEO in Blog Posts","icon":"newspaper","href":"/create-content/seo/seo-in-blog-posts"}]}]},{"group":"AI assistant","pages":[{"group":"Working with the AI assistant","icon":"wand-magic-sparkles","pages":[{"title":"AI assistant for content creation","icon":"wand-magic-sparkles","href":"/create-content/ai-assistant/ai-assistant-content-creation"},{"title":"AI content suggestions","icon":"lightbulb","href":"/create-content/ai-assistant/ai-content-suggestions"},{"title":"AI-generated product descriptions","icon":"tags","href":"/create-content/ai-assistant/ai-product-descriptions"},{"title":"AI-powered SEO optimization","icon":"magnifying-glass-chart","href":"/create-content/ai-assistant/ai-seo-optimization"}]}]}]},{"tab":"Build your app","pages":[{"title":"Build your app","href":"/build-your-app/overview"}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/api/overview"}]},{"tab":"Frameworks","pages":[{"title":"Frameworks","href":"/frameworks/tab-overview"}]},{"tab":"Support","pages":[{"title":"Support","href":"/support/account-management/account-settings"}]}]},"basePath":"","title":"Replacing media files - ButterCMS Docs","buildId":"dpl_2AK98Hxhwu4fUXpx9atbv41cC328","deploymentId":"dpl_2AK98Hxhwu4fUXpx9atbv41cC328","dynamics":["a74be98ba7"],"chunks":["zoom-image-lightbox-T84NdC3b.js","lightbox-handle-r17bVUz3.js"]}