# puNES and the two lives of a Qt based NES emulator > puNES is a Qt based Nintendo Entertainment System emulator written in C and C++ that doubles as an NSF, NSF2 and NSFe music player, ships as CMake builds for Linux, FreeBSD, OpenBSD and Windows, and carries a warning that save states from 0.110 no longer load. **punesemu/puNES** — Qt-based Nintendo Entertaiment System emulator and NSF/NSF2/NSFe Music Player (Linux, FreeBSD, OpenBSD and Windows) - Repository: https://github.com/punesemu/puNES - Stars: 826 · Forks: 48 - Language: C - License: GPL-2.0 - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/punesemu-punes ## One binary that plays NES software and NSF tunes puNES is a Nintendo Entertainment System emulator built on Qt, and it carries a second job that is unusual for an emulator: it is also a music player for the NSF, NSF2 and NSFe formats. The project's screenshots include a dedicated NSF2 player window alongside the main emulator window, so the two functions live in the same application rather than in separate tools. The NSF formats matter because they are the music-only extracts of NES games. A player for them is useful on its own, to listen to game soundtracks without running a game, and the same binary already contains the hardware emulation needed to render an NSF track. The implementation is C and C++ with a Qt interface, and the platforms named in the project description are Linux, FreeBSD, OpenBSD and Windows. That list is the reason to pay attention: this is a Unix and Windows tool, not a browser or mobile project, and the FreeBSD and OpenBSD entries mean the porting work is done at the operating system level rather than through an existing runtime. ## Nightly builds for AppImage, OpenGL and D3D9 The project publishes work-in-progress executables that are always rebuilt from the latest commit, and they are organised by platform and renderer. On Linux there is an x86_64 AppImage. On Windows there are separate 32-bit and 64-bit builds, and each comes in an OpenGL flavour and a D3D9 flavour, so the renderer is chosen at build time rather than at runtime. Two release channels means two very different risk profiles. The tagged releases are v0.111 from 2024-02-25, v0.110 from 2023-01-04 and v0.109 from 2022-02-12. The nightly channel is where the recent work lands, and the project is explicit about what that costs: the notes warn that save states of version 0.110 or earlier are no longer compatible, and that because of the many changes being made to the core of the emulator, new bugs may have been introduced, so if roms no longer work properly compared to version 0.110 the author asks to be told. That is an unusually candid statement for a project README, and it tells a prospective user exactly what nightly builds are for. ## The save state break is the one thing to check before upgrading Save state compatibility is where emulator upgrades usually hurt, and puNES documents the break instead of hiding it. States written by version 0.110 or earlier will not load once the core has been reworked, and the warning sits at the top of the release notes rather than in a changelog buried three pages down. The reason is stated as well: the emulator core itself is being changed extensively, not just the interface. A save state is a snapshot of emulated machine state, so a core rewrite changes the meaning of those bytes. The compatibility promise is not that a state can be migrated, it is that old states are discarded. For a casual user this is a non-issue. For a developer who uses save states to step through a bug, or who keeps a long-running session across builds, it is the thing to plan around. The safe approach is to keep the older tagged binary alongside a newer one, and to treat nightly builds as a separate environment rather than an in-place upgrade of the one you rely on. ## Portable mode has three switches, and one renames the binary puNES can be run so that it keeps its configuration next to the executable instead of in a user directory, and the project documents three distinct ways to trigger that. The first is putting the executable in a folder that contains the puNES.cfg file. The second is renaming the executable with a `_p` suffix, for example: ```bash punes.exe -> punes_p.exe punes64.exe -> punes64_p.exe ``` The third is passing the option directly: ```bash --portable ``` The same executable already exposes a help flag, so the full set of command line options is discoverable without leaving the terminal: ```bash -h ``` Three ways to reach one behaviour is unusual, and each has a different use. The rename trick is the one that matters for distribution, since it lets a packager ship a self-contained folder without a wrapper script, while the explicit option is the one that matters for scripting and for CI images that have no home directory worth writing to. ## Mapper numbers are the honest measure of what will run The project publishes the list of supported mappers as a plain table of numbers, and the table is mostly consecutive with holes in it. Numbers run from 0 upward through the 260s, with gaps where a mapper is not implemented, such as 39, 54, 83, 98, 102, 124, 128 and 131. For anyone deciding whether the emulator can run a particular title, that table is more useful than a feature list, because a mapper is exactly the piece of hardware that a cartridge varies by. A title that uses a mapper outside the list will not run regardless of how fast the emulation is. The table also shows the shape of the project's history. Support for the high mapper numbers is the accumulated work of years, and the gaps mark the ones that nobody has reverse engineered and implemented yet. The repository layout backs this up: the source sits in `src/`, the build is driven by a CMakeLists.txt with a `cmake/` directory and templates such as `compiled.h.in` and `xdelta_config.h.in`, and there is a `misc/` folder, a ChangeLog, an INSTALL file and a NEWS file for the history of each build. ## The tools around the emulator are where the configuration work lives The screenshots of puNES show how much of the application is configuration rather than gameplay. There is a general settings screen, a video filters screen, a slot preview view, a cheat editor, and separate controller mapping screens for Xbox 360 and PlayStation 4 standard controllers. Two of those are worth attention because they are emulator problems with no analogue in a commercial reimplementation. Video filters exist because the NES output is a fixed 256 by 240 picture that looks wrong on a modern display, and the filter settings decide how it is scaled and shaped. The virtual keyboards, shown for the Family BASIC and Subor keyboards, exist because those Japanese peripherals had on-screen keyboards that modern hardware has no equivalent for, so the emulator has to draw them. A cheat editor is likewise a debugging tool, since it lets you alter memory while a game runs. The presence of all of these says the project targets people who want to look at how software behaves, not only people who want to play. The interface is translated into thirteen languages, listed in the project documentation, with the translations maintained through Crowdin. ## GPL-2.0, tagged releases and a gap between commits and tags puNES is distributed under GPL-2.0, with the licence text in the COPYING file at the root of the repository. That is a copyleft licence, so a modified and distributed build carries the obligation to keep the source available under the same terms. Anyone embedding parts of this codebase in a larger product, commercial or otherwise, needs to read the licence text and work out what the obligations are for their own distribution, and the project's own legal terms are the starting point rather than a substitute for that reading. The maintenance picture has two halves that should not be confused. The last push to the repository was on 2026-09-01 and the repository is not archived, so the code is still being worked on. The newest tagged release, however, is v0.111 from 2024-02-25, and the two before it are v0.110 from 2023-01-04 and v0.109 from 2022-02-12. Packaging is handled outside the repository, with a Repology badge tracking the distribution packages and a Flathub entry for the flatpak build, and the 32-bit Windows builds are stated to be compatible with Windows XP. The natural conclusion for a user is to pick the channel that matches your need: a distribution package or the Flathub build for a stable system, and the nightly build only when you specifically want the current core. ## Conclusion puNES suits a developer on Linux, FreeBSD, OpenBSD or Windows who wants one application that both runs NES software and plays NSF music files, and who can live with a save format that changes between core revisions. It is the wrong choice if your existing save states matter, if you need a headless core you can embed in your own frontend, or if you need a tagged release with a support commitment, since the last push was on 2026-09-01 while the newest tag is v0.111 from 2024-02-25. Verify first that the mapper you need is in the supported list and that the WIP build you plan to run has not broken the titles you care about. ## FAQ ### Which platforms does puNES run on? puNES is described as a Qt based Nintendo Entertainment System emulator and NSF, NSF2 and NSFe music player for Linux, FreeBSD, OpenBSD and Windows. Work in progress builds include an x86_64 Linux AppImage and 32-bit and 64-bit Windows builds in OpenGL and D3D9 flavours. ### How do I make puNES run in portable mode? There are three ways: put the executable in a folder containing the puNES.cfg file, rename the executable with a `_p` suffix such as `punes.exe` to `punes_p.exe`, or run the emulator with the `--portable` option. The available command line options are listed by starting puNES with the `-h` argument. ### Are puNES save states from older versions still compatible? No. The project warns that save states of version 0.110 or earlier are no longer compatible, because the emulator core is being changed extensively. The same note says new bugs may have been introduced and asks users to report roms that stopped working compared to version 0.110. ### Can puNES play NSF music without running a game? Yes. puNES is both an emulator and a music player for the NSF, NSF2 and NSFe formats, and the project screenshots include a dedicated NSF2 player window separate from the main emulator window. ### What licence is puNES released under? puNES is released under GPL-2.0, with the licence text in the COPYING file at the repository root. Distribution is also tracked through Repology packages and a Flathub entry, and the 32-bit Windows builds are stated to be Windows XP compatible. ## Sources - [Issues](https://github.com/punesemu/puNES/issues) - [License: GPL-2.0](https://github.com/punesemu/puNES/blob/master/LICENSE) - [punesemu/puNES on GitHub](https://github.com/punesemu/puNES) - [README](https://github.com/punesemu/puNES/blob/master/README.md) - [Releases](https://github.com/punesemu/puNES/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/punesemu-punes