You can add images and videos to the iPhone Simulator by dragging files onto the Simulator window, by using the xcrun simctl addmedia command, or by saving files from Safari within the Simulator. Each method places media into the Photos library where your app can access it through PhotoKit or UIImagePickerController.

Method 1: Drag and Drop

The fastest way to add media during development is to drag one or more files from Finder directly onto the running Simulator window.

1. Launch the Simulator (from Xcode or via open -a Simulator).
2. Locate the image or video file in Finder.
3. Drag it onto the Simulator window.

The Simulator imports the file into the Photos app automatically. You can drag multiple files at once. Supported formats include JPEG, PNG, HEIC, GIF, MOV, MP4, and M4V.

After the drop, open the Photos app inside the Simulator to confirm the import. If your app uses PHPhotoLibrary, the newly added asset will appear in query results immediately.

Method 2: xcrun simctl addmedia (Command Line)

The simctl addmedia command is the preferred approach when you need to script media imports or add files as part of a CI pipeline.

1# Add a single image to the currently booted simulator
2xcrun simctl addmedia booted ~/Desktop/test-photo.jpg
3
4# Add multiple files at once
5xcrun simctl addmedia booted photo1.png photo2.png video.mp4
6
7# Target a specific simulator by UDID
8xcrun simctl addmedia 4A2B3C4D-5E6F-7890-ABCD-EF1234567890 ~/assets/hero.png

To find the UDID of a specific simulator, list all available devices:

xcrun simctl list devices

This prints output like:

-- iOS 17.5 --
    iPhone 15 Pro (4A2B3C4D-5E6F-7890-ABCD-EF1234567890) (Booted)
    iPhone SE (3rd generation) (1A2B3C4D-...) (Shutdown)

Scripting Bulk Imports

For test suites that require a specific photo library state, automate the import in a setup script:

1#!/bin/bash
2# seed-simulator-media.sh
3SIMULATOR_UDID="$1"
4MEDIA_DIR="./test-fixtures/media"
5
6# Boot if not already running
7xcrun simctl boot "$SIMULATOR_UDID" 2>/dev/null
8
9# Import all test assets
10for file in "$MEDIA_DIR"/*; do
11  xcrun simctl addmedia "$SIMULATOR_UDID" "$file"
12done
13
14echo "Imported $(ls "$MEDIA_DIR" | wc -l | tr -d ' ') files"

Method 3: Save from Safari Inside the Simulator

If you need to test the full user flow of saving an image from the web:

1. Open Safari inside the Simulator.
2. Navigate to any URL hosting the image (even file:// URLs work for local files served via python3 -m http.server).
3. Long-press the image and tap "Add to Photos" or "Save Image."

This method exercises the same permission prompts and save flow that real users encounter, making it useful for testing PHPhotoLibrary authorization dialogs.

Method 4: Programmatic Import in XCTest

For UI tests that need media available before each test run, you can add assets programmatically using simctl from within your test plan's setup:

1import XCTest
2
3class MediaSetupTests: XCTestCase {
4    override class func setUp() {
5        super.setUp()
6        let process = Process()
7        process.executableURL = URL(fileURLWithPath: "/usr/bin/xcrun")
8        process.arguments = [
9            "simctl", "addmedia", "booted",
10            Bundle(for: Self.self).path(forResource: "test-image", ofType: "jpg")!
11        ]
12        try? process.run()
13        process.waitUntilExit()
14    }
15}

Alternatively, use a pre-action script in your Xcode scheme's Test section to run xcrun simctl addmedia before the test bundle launches.

Comparison of Methods

Supported File Formats

Attempting to import an unsupported format (such as RAW .dng on older simulator runtimes) will fail silently with addmedia or show a brief error animation with drag-and-drop.

Resetting the Photo Library

During testing you may need to clear all media and start fresh. You have two options:

1# Option 1: Erase all content and settings (nuclear option)
2xcrun simctl erase booted
3
4# Option 2: Delete only the Photos database
5rm -rf ~/Library/Developer/CoreSimulator/Devices/<UDID>/data/Media/DCIM
6rm -rf ~/Library/Developer/CoreSimulator/Devices/<UDID>/data/Media/PhotoData
7# Then reboot the simulator
8xcrun simctl shutdown booted && xcrun simctl boot <UDID>

Option 1 resets everything including app installs and user defaults. Option 2 preserves your installed apps but requires a reboot for Photos to rebuild its database.

Common Pitfalls

Dragging files while the Simulator is locked. The import silently fails if the Simulator screen is on the lock screen. Unlock the Simulator first or use xcrun simctl addmedia, which bypasses the lock screen entirely.

Using unsupported codecs. Some MOV files encoded with ProRes or other professional codecs will not import. Transcode to H.264/AAC first with ffmpeg -i input.mov -c:v libx264 -c:a aac output.mp4.

Expecting persistent media after simctl erase. The erase command wipes all user data including Photos. If your CI pipeline erases the simulator between test runs, re-import media in the setup phase of each run.

Not waiting for import completion in scripts. xcrun simctl addmedia is synchronous and blocks until the import finishes, so you do not need a sleep after it. However, if you import a large number of files in a loop, the Photos indexer may still be processing when your test starts. Add a short delay or poll for asset count via PHPhotoLibrary in your test setup.

Path spaces without quoting. When using simctl addmedia in a script, file paths containing spaces must be quoted. Unquoted paths produce a "file not found" error for each word after the space.

Summary

Adding media to the iPhone Simulator comes down to two primary approaches: drag-and-drop for manual testing and xcrun simctl addmedia for automated workflows. The addmedia command accepts any iOS-compatible format, works on booted or specified simulators by UDID, and can be scripted into CI pipelines or XCTest pre-actions. For testing photo-permission flows, use the Safari save method. Always verify imports in the Photos app and remember that simctl erase wipes all media.