xcrun simctl addmedia booted /path/to/file.jpg in Terminal. Both methods immediately populate the Simulator’s Photos app without requiring a restart.Why this happens
When you create or reset an iOS Simulator in Xcode, its media storage is completely isolated from your Mac’s Photos library. Depending on the simulator runtime and whether you recently erased its contents, the Simulator’s Photos app may contain only a few default sample images or appear completely empty.
Because of this isolation, testing UIImagePickerController, PHPickerViewController, or SwiftUI’s PhotosPicker often shows a “No Photos” state or lacks the specific file formats—such as PNGs, HEICs, transparent images, or .mov videos—that your app needs to handle.
How to fix it
1. Drag and drop media onto the Simulator
The fastest way to populate the Simulator’s photo library is directly from Finder:
- Boot your target device in the Simulator app.
- Open Finder and select one or more image or video files (such as
.jpg,.png,.heic, or.mov). - Drag the files over the running Simulator window and drop them.
The Simulator automatically launches the Photos app and imports the files into the library. They become available immediately to UIImagePickerController and PhotosPicker without restarting the device.
2. Use xcrun simctl addmedia in Terminal
If you want a repeatable, scriptable way to seed test media—for example, after running xcrun simctl erase or in a UI test setup script—use Xcode’s simctl command-line tool.
To add a single photo to the currently booted simulator:
xcrun simctl addmedia booted ~/Desktop/test-photo.jpg
You can also pass multiple images and videos in a single command:
xcrun simctl addmedia booted ~/Desktop/avatar.png ~/Desktop/sample-clip.mov
If you have multiple simulators running at the same time, find the specific device UDID first:
xcrun simctl list devices | grep Booted
Then replace booted with that UDID:
xcrun simctl addmedia XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX ~/Desktop/test-photo.jpg
simctl addmedia updates the Simulator’s media database right away, so no reboot is required.
3. Save images from Safari inside the Simulator
If you are already browsing test assets on the web or testing a download flow inside the Simulator, you can save images directly from Safari:
- Open Safari in the iOS Simulator and navigate to the image URL.
- Click and hold (long-press) on the image until the context menu appears.
- Tap Save to Photos (or Add to Photos).
On older Simulator runtimes where dragging an image onto the window opens Safari instead of the Photos app, use this same long-press gesture on the displayed image to save it into the library.
4. Copy files to the Simulator DCIM folder (legacy workaround)
Before simctl addmedia existed, developers copied files manually into the simulator’s DCIM directory on disk:
~/Library/Developer/CoreSimulator/Devices/<Simulator-UDID>/data/Media/DCIM/100APPLE
This approach requires naming files sequentially as IMG_0001.JPG alongside a matching 75×75 pixel thumbnail named IMG_0001.THM, and then rebooting the Simulator so the system indexes the files. Unless you are debugging low-level CoreSimulator storage behavior, prefer xcrun simctl addmedia or drag and drop instead.
5. Verify your picker code in SwiftUI
Once you have imported media into the Simulator, test that your app can read it. For modern apps, PhotosPicker from PhotosUI runs out-of-process and does not require requesting full photo library permission:
import SwiftUI
import PhotosUI
struct MediaTestView: View {
@State private var selectedItem: PhotosPickerItem?
@State private var selectedImage: Image?
var body: some View {
VStack(spacing: 16) {
if let selectedImage {
selectedImage
.resizable()
.scaledToFit()
.frame(maxHeight: 240)
} else {
Text("No photo selected")
.foregroundStyle(.secondary)
}
PhotosPicker("Choose Photo", selection: $selectedItem, matching: .images)
}
.onChange(of: selectedItem) { _, newValue in
Task {
if let data = try? await newValue?.loadTransferable(type: Data.self),
let uiImage = UIImage(data: data) {
selectedImage = Image(uiImage: uiImage)
}
}
}
}
}
If your app still uses UIImagePickerController or queries PHPhotoLibrary directly, verify that your target’s Info.plist includes the NSPhotoLibraryUsageDescription key with a clear reason string; otherwise, the app will crash when attempting to access the library.
How to prevent it
- Keep a dedicated folder of test assets (portrait, landscape, transparent PNG, HEIC, and
.movvideo) in your repository or home directory so you can quickly drag them into any new simulator. - Add an
xcrun simctl addmedia booted ...step to your local bootstrap or UI-testing script so freshly erased simulators are always seeded automatically. - Avoid erasing all content and settings on your primary development simulator unless you need a clean state; erasing wipes the
Mediadirectory along with installed apps. - Test with both
PhotosPickerandUIImagePickerControllerusing diverse aspect ratios and file formats, not just the default sample photos.
FAQ
Where are iOS Simulator photos stored on macOS?
Each simulator has an isolated data container at ~/Library/Developer/CoreSimulator/Devices/<UDID>/data/Media/. Inside that folder, imported photos and videos are managed in the DCIM and PhotoData directories.
Can I add videos to the iOS Simulator the same way?
Yes. Both drag-and-drop and xcrun simctl addmedia booted /path/to/video.mov support video files such as .mov and .mp4. After importing, the video appears in the Simulator’s Photos app and in pickers configured for video media.
Why did dragging a photo onto the Simulator open Safari instead of Photos?
Older iOS Simulator versions treated dropped files as URLs to preview in Safari rather than media to import. If that happens, long-press the image in Safari and choose Save to Photos, or use xcrun simctl addmedia booted in Terminal instead.
Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.