# UnityNativeGallery for saving and picking media on Android and iOS

> UnityNativeGallery is a native Unity plugin for saving images and videos to Android Gallery or iOS Photos, and for selecting existing media. Its value is focused platform integration, but iOS paths, Android URI persistence, and build configuration introduce constraints teams should account for.

**yasirkula/UnityNativeGallery** — A native Unity plugin to interact with Gallery/Photos on Android & iOS (save and/or load images/videos)

- Repository: https://github.com/yasirkula/UnityNativeGallery
- Stars: 1,623 · Forks: 215
- Language: Objective-C++
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/yasirkula-unitynativegallery

## What UnityNativeGallery handles inside a Unity project

UnityNativeGallery addresses a specific gap between Unity code and the native media libraries on two mobile platforms. It can write images and videos to Gallery on Android and Photos on iOS. It can also present the device media picker so a user can select an image or video and return that selection to Unity.

The intended audience is a Unity developer building an Android or iOS application that handles user media. The plugin accepts raw media bytes for saving and exposes gallery or photo selection as native operations. That makes it relevant to editor tools that export screenshots, content-creation applications, social or communication features, and utilities that import media selected by the user.

The platform boundary is strict. Windows, macOS, and Linux builds are not supported targets. Editor functionality exists only for preview and uses Unity's Editor-only file panel API, so editor behavior should not be treated as evidence that the same media integration works in a desktop player. VR use is also not treated as an ordinary player scenario by the README, which points users to an issue discussion about calling the plugin during `Awake` or `Start`.

This is not a general-purpose file browser, media metadata library, or cloud storage client. Its documented scope is saving and picking images or videos through the operating system's media facilities. Projects needing desktop file-system integration, broad archive handling, or uniform paths on every platform need a different design.

## The native save and media-picking paths

For saving, the plugin exposes a byte-oriented API through `NativeGallery.SaveImageToGallery`. The caller supplies the encoded media bytes, an optional album name, a filename, and optionally a `MediaSaveCallback`. This design puts Unity-side media generation ahead of the native save operation: application code produces bytes, while the plugin passes them to the platform gallery service.

Android save locations are documented as `DCIM/album/filename`. On iOS 14 and later, media is saved to the default Photos album, so the `album` argument is ignored. Earlier iOS versions can save to the requested target album. The filename must include the file extension. Omitting one can prevent an image or video from being saved correctly.

The callback receives `bool success` and `string path`. Android can return the save location, although the path may be an abstract Storage Access Framework path for which `File.Exists` returns `false`. The README states that the path is `null` on iOS. Consequently, the return value cannot be treated as a cross-platform durable file identifier.

Picking uses the native gallery or Photos interface and supports an image or video. On Android, the selected item may come from a content URI rather than a permanent filesystem path. If the original source path cannot be determined, the plugin copies the selection to a fixed location under `temporaryCachePath`. That copy can later be overwritten by another `PickImage` call, while the original source can also be deleted by the user or operating system. This path behavior is one of the plugin's most important design constraints.

## Installing Native Gallery through documented package routes

The repository documents five installation paths: importing `NativeGallery.unitypackage`, moving the repository's `Plugins` folder into the Unity project's `Assets` folder, installing the Asset Store package, adding the Git repository through Unity Package Manager, or using OpenUPM.

For an OpenUPM-enabled project, the documented package command is:

```bash
openupm add com.yasirkula.nativegallery
```

This command adds the package named `com.yasirkula.nativegallery`, which is also the name recorded in `package.json`. The repository also documents a Unity Package Manager git URL, but the README does not provide a manifest snippet or a complete Package Manager dialog procedure, so there is no additional example to reproduce here.

After installation, the README states that Android requires no manual setup. The plugin's documented save method is:

```csharp
NativeGallery.SaveImageToGallery( byte[] mediaBytes, string album, string filename, MediaSaveCallback callback = null )
```

The application must provide the media bytes before calling that method. The plugin does not generate them. On Android, the documented destination pattern is `DCIM/album/filename`. On iOS 14 or later, the media is saved to the default Photos album instead of the requested album.

The callback can inspect `bool success` and `string path`. Because `path` is `null` on iOS and may not pass `File.Exists` on Android, the callback should be treated as completion and diagnostic information rather than a promise of a portable local path. The README also warns that NativeGallery never overwrites existing media. A filename conflict causes the plugin to generate a different name.

## iOS deployment and permission requirements

UnityNativeGallery offers automated and manual iOS setup. The automated route exposes settings at `Project Settings/yasirkula/Native Gallery`. Developers can change `Photo Library Usage Description` and `Photo Library Additions Usage Description`. For Unity 2017.4 or earlier, the same settings page can indicate whether the minimum iOS deployment target is at least 8.0 through `Deployment Target Is 8.0 Or Above`.

The clearest version constraint is Xcode 12 or later. The README requires an application targeting iOS 14 or later to use that Xcode version to avoid permission problems. This requirement applies to the build environment and native project generation, not merely to runtime code written in C#.

Projects unable to use automated setup are directed to the repository wiki page titled `Manual-Setup-for-iOS`. The README does not reproduce the manual steps, so this article does not invent project-setting changes, capability entries, or native-code modifications.

There is also a deliberate platform limitation around return paths. Saved and picked files can reside in an internal iOS directory that the plugin cannot access, and the README explicitly says that neither the saved image path nor the original picked image path can be fetched on iOS. An application should therefore use picked media without assuming that a returned path can be reopened after restart.

## Android URI lifetime and build failure modes

Android picking is convenient for immediate access but does not guarantee permanent ownership of the selected source. The README says that on Android 13 and later, with `Target API Level` 33 or higher, a saved path can stop working after an app restart. The source may be removed from Gallery, deleted by the operating system, or overwritten by `NativeGallery` when the plugin cannot identify an original file and uses its fixed `temporaryCachePath` fallback.

The documented durable approach is to copy picked media to `persistentDataPath`. The plugin also exposes `GrantPersistableUriPermission` through `NativeGalleryMediaPickerFragment`. The README warns that persistable permission has a hard limit of 512 files. This is narrower than unrestricted file access and should be considered before selecting that route.

Build configuration can also affect adoption. The plugin uses Gradle `7.5.1` and Android Gradle Plugin `7.4.2`. A D8 `NullPointerException` while transforming `NativeGallery-.aar` is documented as a possible Unity compatibility problem, with a link to Unity's Android Gradle compatibility documentation. If `ClassNotFoundException: com.yasirkula.unity.NativeGallery` appears after confirming an up-to-date plugin, the README instructs users to enable `Custom Proguard File` and retain the plugin classes.

Storage settings are another concrete boundary. The troubleshooting text calls for `Write Permission` set to `External (SDCard)`. A separate manifest entry using `tools:node="replace"` may be needed for denied save operations. The README also documents an Android 10 workaround involving `android:requestLegacyExternalStorage`, but warns that it requires Android SDK 29 or later and should be removed by editing `NativeGallery.aar` if that SDK level cannot be used.

## Maintenance, licensing, and the practical alternative

The repository is not archived, and its last push was on 2026-09-24. Release activity is visible in three recent tags: `v1.9.3` on 2026-05-10, `v1.9.4` on 2026-06-30, and `v1.9.5` on 2026-09-24. The current `package.json` also records version `1.9.5`. These facts indicate recent code and release activity, but they do not remove the need to inspect Unity and native platform compatibility when upgrading.

The repository identifies its license as MIT through `LICENSE.txt`. That designation allows use under the terms included in that file, while the exact obligations depend on the full license text. The open-source repository and the Asset Store package are presented through separate installation routes. The README does not state that every distribution channel carries identical support terms.

A real alternative is to write a native Android and iOS media plugin directly for the specific application. UnityNativeGallery wraps common save and pick behavior, including Android URI copying and iOS album handling. A custom plugin can expose only the native APIs, permissions, ownership model, callbacks, and durable-file operations required by one project. That approach costs more platform-specific maintenance, but it is more appropriate when uniform cross-platform paths, custom photo-library scopes, background transfer, or application-owned storage are requirements. Another practical alternative is to keep Unity code independent of the native library and define an interface that can be replaced when either platform's media policy changes.

## Conclusion

UnityNativeGallery fits Unity applications that need a small native bridge for saving or selecting photos and videos on Android and iOS. It is a poor fit for desktop or VR builds, projects that require portable file paths on iOS, or Android applications that retain picked media without copying it. Before adoption, verify the target Unity version, iOS build requirements, Android storage configuration, and whether selected media must remain available after the source changes.

## FAQ

### Can UnityNativeGallery retrieve a durable file path for media on iOS?

No. The README says saved and picked media can reside in an internal iOS directory that the plugin cannot access, so it cannot return the saved image path or original picked image path on iOS.

### Does UnityNativeGallery work in Windows, macOS, Linux, or VR builds?

Only Android and iOS player platforms are supported. Editor functionality is for preview only, while the VR case requires following the repository's separate issue discussion rather than assuming normal player behavior.

### How should picked Android media be kept available after the app restarts?

Copy the selected media to `persistentDataPath`, as recommended in the README. Persistable URI permission is another documented option, but it has a hard limit of 512 files.

## Sources

- [Issues](https://github.com/yasirkula/UnityNativeGallery/issues)
- [License: MIT](https://github.com/yasirkula/UnityNativeGallery/blob/master/LICENSE)
- [README](https://github.com/yasirkula/UnityNativeGallery/blob/master/README.md)
- [Releases](https://github.com/yasirkula/UnityNativeGallery/releases)
- [yasirkula/UnityNativeGallery on GitHub](https://github.com/yasirkula/UnityNativeGallery)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yasirkula-unitynativegallery