IINA 1.5.0: A macOS video player built on mpv, with a build process you should read before adopting
GitHub describes it as The modern video player for macOS.. The repository metadata lists Swift as its primary language. The metadata lists the GPL-3.0 license. This article stays within the project description and details documented in the GitHub repository README.
At a glance
- What is it?
- IINA is a GPL-3.0 Swift video player for macOS that wraps mpv. Its feature list is broad, but its build and update process demands attention from anyone planning to compile it themselves.
- Who is it for?
- Adopt IINA if you want a native macOS player that exposes mpv's power through a polished GUI and you are comfortable with its GPL-3.0 license and dependency on a separately built mpv. Do not adopt it if you need a player that you can build with a simple package manager command or if you require support for macOS versions older than 11.0.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Swift, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- iina/iina47,131 ★ · +1,196
| Repository | 2026-08-13 | 2026-11-15 |
|---|---|---|
| iina/iina | 45.9k | 47.1k |
1,196 Stars in the last 94 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What IINA actually solves for macOS users
IINA addresses a specific gap: a native macOS video player that does not compromise on codec support or configurability. The README states it is based on mpv, which provides 'the best decoding capacity on macOS.' For users who need to play a wide variety of formats, including those not supported by QuickTime, IINA offers a graphical interface over mpv's engine. It is designed for macOS 11.0 and later, so it targets users on recent operating systems. The project is for people who want an mpv-like experience without living in the terminal, but who still want access to mpv's configuration files and script system. It is not for users who need a simple player with minimal dependencies; the build process makes that clear.
The architecture: Swift front end, mpv back end
IINA's architecture is a split between a Swift-based macOS application and the mpv media engine. The README explains that mpv is the playback core, and IINA provides the native macOS interface, including Force Touch, picture-in-picture, and Touch Bar support. The project generates Swift bindings to mpv's API using a script called `other/parse_doc.rb`, which fetches the latest mpv documentation and produces files like `MPVOption.swift`, `MPVCommand.swift`, and `MPVProperty.swift`. This means the player's control surface is tightly coupled to mpv's version. When mpv's API changes, the player source code may also need changes, as the README notes. This is a maintenance point: you cannot simply swap in a newer mpv without regenerating those bindings and potentially adjusting code.
Getting it running: the pre-compiled library path
The simplest way to build IINA is to use the pre-compiled libraries. The README gives a clear command: run `./other/download_libs.sh` to fetch universal binaries, or use `--arch` to get `arm64` or `x86_64` specific ones. You can also control download parallelism with `--parallel <N>`. After that, you open `iina.xcodeproj` in the latest public version of Xcode and build. A critical warning: the README says 'IINA may not build if you use any other version' of Xcode. This is a concrete constraint. For older IINA versions, you must change `DYLIBS_DOWNLOAD_PATH` in the script to point to the corresponding dylib list, for example `https://iina.io/dylibs/1.2.0/universal/fileList.txt`. This path is the easiest, but it ties you to the dylibs IINA provides.
Building mpv manually: a long, brittle road
If you want to build your own mpv, the README outlines a multi-step process that is not for the faint of heart. The README says to build your own copy of mpv, and points to IINA's official build scripts at github.com/iina/deps-buildscripts, which build mpv and all other dependencies. After that you run `other/parse_doc.rb` to regenerate the Swift bindings, link yt-dlp into `deps/executable`, and then fix up the `.dylib` references and the Copy Dylibs and Link Binary With Libraries build phases in Xcode. This is not a casual build.
A real limitation: the yt-dlp symlink and online media
One specific limitation is the dependency on yt-dlp for online media. The README instructs you to create a symlink: `ln -s $(which yt-dlp) deps/executable/youtube-dl`. Notice the target name is `youtube-dl`, not `yt-dlp`. If you do not have yt-dlp installed, or if the symlink is missing, any feature that relies on online media playback will not work. The README lists an official plugin called 'Online Media' that enhances online streaming and downloading, but that plugin presumably depends on this executable. So if you are building from source, you must remember this step. This is a failure mode: you could have a perfectly built player that cannot play YouTube URLs because you skipped the symlink.
Maintenance and upgrade costs: version coupling and nightly risk
IINA's maintenance cost is tied to mpv's API. The `parse_doc.rb` script exists because mpv's options, commands, and properties change. Every time you update mpv, you must regenerate those Swift files and potentially modify the player source. The README says this is 'only needed when updating libmpv,' but it is a real chore. Also, the project offers nightly builds generated automatically for every commit, but the README warns they 'might be buggy and unusable.' So if you want a stable player, you must stick to tagged releases like v1.5.0. The project is actively maintained, with releases on 2026-09-04, 2026-09-19 and 2026-10-03, but that also means you may feel pressure to upgrade to keep up with mpv changes. The license is GPL-3.0, which has implications if you plan to distribute modified versions; you should understand those before embedding or forking.
Alternatives: mpv itself and other macOS players
The obvious alternative is mpv itself, which IINA wraps. If you do not need a native macOS GUI, you can use mpv directly with a config file and get the same decoding engine without the Swift layer. The difference is in the interface: mpv is keyboard-driven and minimal, while IINA adds a full macOS interface with Touch Bar, Force Touch, and an on-screen controller. Another alternative is VLC, which is also open source but uses its own decoding stack, not mpv. VLC is easier to build on multiple platforms, but it does not offer the same level of mpv configuration passthrough. For users who want mpv's exact behavior, IINA is a closer match. For users who want a simpler player, VLC or even the built-in QuickTime might suffice, though QuickTime lacks the codec support.
Who should adopt IINA and what to verify first
IINA is a strong choice for macOS users who want a modern, native player with deep mpv integration. It is also good for developers who want to contribute to a Swift project that interacts with a C-based library. But you should verify your macOS version is 11.0 or higher, and you should test the latest stable release (v1.5.0) on your hardware before relying on it. If you plan to build from source, verify that you have the latest Xcode, because the README warns other versions may fail. Also, check that you can either download the pre-compiled dylibs or successfully build mpv with the official build scripts. If you are not prepared for that build process, use the official binaries from the website or GitHub releases. For anyone who needs a player that is simple to compile or that does not carry GPL obligations, IINA is not the right tool.
Editorial conclusion
Adopt IINA if you want a native macOS player that exposes mpv's power through a polished GUI and you are comfortable with its GPL-3.0 license and dependency on a separately built mpv. Do not adopt it if you need a player that you can build with a simple package manager command or if you require support for macOS versions older than 11.0. Before adopting, verify that your macOS version meets the 11.0+ requirement, check that the latest release (v1.5.0) works with your hardware, and confirm that you can either use the pre-compiled dylibs or successfully build mpv with IINA's official build scripts. The project is actively maintained, with v1.5.0 released on 2026-10-03, but nightly builds are explicitly warned as potentially buggy, so stick to stable releases for production use.
Frequently asked questions
What is IINA?
The modern video player for macOS, written in Swift, based on mpv for decoding and released under GPL-3.0. It supports macOS 11.0 and later, offers subtitles, playlists, chapters, picture-in-picture, an on screen controller and a plugin system, and ships a command line tool with browser extensions.
Is IINA safe to use?
It is based on mpv, and stable and beta releases are published on the GitHub release page and iina.io. The README warns that nightly builds are generated by GitHub for every commit and might be buggy and unusable, and notes that the User Scripts plugin runs custom JavaScript snippets.
Which is better for macOS, IINA or VLC?
The README makes no comparison with VLC. What it states is that IINA is based on mpv, which it credits with providing the best decoding capacity on macOS, and that IINA targets modern versions of macOS, 11.0 and later.
Is IINA only for Mac?
Yes. It is described as a video player for macOS designed with macOS 11.0 and later in mind, and it is a Swift project built from iina.xcodeproj in the latest public version of Xcode.
Official sources
Where developers are discussing it
Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 0 in the last 30 days; newest first.
- IINA 1.5.0Hacker News · Oct 3, 2026 · 17 points · 3 comments
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/iina-iina)Star history chart for your README
[](https://hysenlabs.com/projects/iina-iina)Was this useful?