New WordPress site (greenfield)
Step-by-step: install WP to S3 on a new site so all Media Library uploads go to S3 — no bulk migration.
Use this guide when the site is new or you do not need to move an existing wp-content/uploads library. You will install the plugin, connect a bucket, enable live offload, and use the Media Library as usual.
You do not run Migrate in this path. Migration is only for pre-existing local files.
Before you start
- Single-site WordPress 6.0+ (multisite is unsupported).
- An S3-compatible bucket and access keys with at least:
s3:PutObject,s3:GetObject,s3:DeleteObject,s3:ListBucket,s3:HeadObject. - Ability to install plugins (or SFTP + file access).
Steps
Install WordPress as usual (hosting wizard, Local, Docker, etc.) and finish the famous five-minute install.
Install WP to S3 from a release zip or from source.
Follow Installation until the plugin is Active.Create or choose a bucket on your provider (Amazon S3, R2, MinIO, Spaces, Linode, …).
Note endpoint, region, path-style requirement, access key, and secret.Open Media → WP to S3 → Settings.
Fill connection settings:
- Pick a provider preset if applicable (fills endpoint/region/path-style hints).
- Enter endpoint, region, bucket, access key, secret key.
- Optional: key prefix (e.g.
prod→ keys likeprod/2026/08/photo.jpg). - Leave Delete local after upload unchecked for the first day of production (safer).
Click Test.
Confirm PUT, GET, and DELETE all pass (HTTP statuses shown on success).
If anything fails, fix keys/endpoint/bucket policy and re-test before saving.Click Save Changes (unlocked after a successful Test when connection fields changed).
Enable the plugin (checkbox Enable S3 upload + serve hooks), then Save Changes again if needed.
Upload a test image via Media → Add New Media File.
Confirm offload:
- Media Library S3 status column shows offloaded (or dual if local was kept).
- Attachment metabox shows the object key under your prefix.
- Optional CLI:
wp s3 doctorreportsconnection_test: OKandenabled: yes.
Optional hardening after you trust the setup:
- Turn on Delete local after upload so disk stays thin (same-host stream still serves URLs).
- Or set a Public base URL / CDN — see Same-host vs CDN.
Keep uploading. All new Media Library files follow the offload path. No migrate job is required.
What you should not do on greenfield
- Do not start Migrate unless you also have old local files you need in the bucket.
- Do not enable delete local before Test passes and you have confirmed a real upload.
- Do not set historic content rewrite tools unless you use a public/CDN base URL and understand the dry-run.
Troubleshooting
| Symptom | Check |
|---|---|
| Test PUT fails 403 | Key permissions, bucket policy, wrong path-style |
| Test fails “not configured” | Missing endpoint, bucket, or keys; save constants if using wp-config only |
| Plugin missing under Media | Capability (manage_options); user role |
| New upload stays local only | Enabled off; doctor configured/sdk; PHP errors in debug log |
Next
- Usage — day-to-day Media Library tools
- Configuration — constants, presets, secrets
- WP-CLI —
wp s3 doctor