The "for Linux" download builds the Linux game from your own dump: Pokopia recompiled for your computer's x86-64 CPU, played with a Vulkan renderer. It is the Windows build's recompiler and runtime ported to Linux, so it plays the same way (keyboard and mouse, controllers, Link Play).
Linux and the Steam Deck are a full release since 1.4.0, after six public betas on Steam Decks and Linux PCs. On a Steam Deck the game starts in its own handheld mode, with its lighter settings. If something goes wrong, the report (the last section) tells us what happened. Nothing of the game is in the download: everything made from your dump stays in your build folder.
What you need
- A Steam Deck (LCD or OLED, SteamOS 3.6 or newer), or a 64-bit Linux PC with a CPU that has AVX2 and FMA3 (Intel Haswell from 2013, AMD Excavator from 2015, and anything newer) and a Vulkan 1.3 GPU driver (Mesa RADV or ANV, or NVIDIA's).
- 16 GB of memory (the Steam Deck has it) and about 15 GB free where the build folder goes.
- Your dump of the game, as for the other builds (the README's "What you need"): the folder with
exefsandromfs(orupdates/<version>/). - Python 3.10 or newer (SteamOS has it), git (SteamOS has it), and the .NET 10 runtime (step 3 installs it into your home folder).
No root, no sudo, no compiler: the download carries its own tools in linux/bin (see linux/bin/MANIFEST.txt and THIRD-PARTY-NOTICES.txt).
The easy way: the AppImage
Pokopia-Native-<version>-x86_64.AppImage is Pokopia Native as one file: the app, with everything it needs inside (its own Python, the
.NET runtime, the Linux tools and nxnative): no terminal steps, no Python packages, no .NET install. (Up to 1.4.1 it was
Pokopia-Native-Builder-<version>-x86_64.AppImage and opened the builder's window.)
- Make it executable: in Dolphin (the Steam Deck's file manager), right-click it → Properties → Permissions → tick Is executable.
Or in a terminal:
chmod +x ~/Downloads/Pokopia-Native-*.AppImage - Double-click it. The first start unpacks it to
~/.local/share/pokopia-native/builder/<version>(about 1 GB, once per version; the games you build use its Python and .NET from there), then the Pokopia Native app opens. - The app walks you through the first build: your game files, a check of your computer, the build, then Play. From then on the app is where you play, set up mods, bring your save from Windows, the phone or a Mac (Saves and DLC), play together (Link Play) and update.
On a Steam Deck, do the first build in Desktop Mode (press the Steam button → Power → Switch to Desktop). Then, in the app,
Add to Steam (on Home, or Settings → App → Steam). Steam has to be closed while it adds: right-click Steam's icon in the taskbar →
Exit. Back in Game Mode, Pokopia Native is in your library under Non-Steam: it opens the app with Play ready (Settings → App →
"Starting from Steam or the desktop" can start the game right away instead). The shortcut starts ~/.local/share/pokopia-native/pokopia-native,
which every start of the AppImage points at its own version, so it keeps working after updates and without the AppImage.
The game itself is still built on your computer from your own dump, into the build folder; the AppImage carries nothing of the game. The report
(the last section) is ~/Downloads/Pokopia-Native-*.AppImage report in a terminal (or Help → Report a problem in the app): it finds
your build folder by itself. If the AppImage does not start at all, run it in a terminal with --appimage-extract-and-run after its name (a
system without FUSE), and say so in the report. Pokopia-Native-*.AppImage builder-window opens the builder's own window of 1.4 and before
(it draws with your desktop's fonts; on a system older than 2022, glibc 2.35, it falls back to one plain bitmap font, which POKOPIA_TK=x11
forces). To remove Pokopia Native, delete the AppImage, ~/.local/share/pokopia-native/builder and ~/.local/share/pokopia-native/pokopia-native;
your builds and saves are elsewhere and stay.
A new version: the app tells you when one is out (it asks the website and GitHub once a day; Settings → App turns that off). Update now backs up your save, fetches the new AppImage beside the old one, checks it, and opens it to update your game; the version before stays, so Versions can go back to it. The old AppImage can be deleted afterwards. A 1.4 builder window's Download and update lands in the app the same way.
Everything below is the same build without the AppImage, from the "for Linux" zip and a terminal. The zip has the app too
(pokopia-native at its top): once steps 2 to 4 below are done, POKOPIA_PY=~/pokopia-venv/bin/python ~/pokopia-native-*/pokopia-native
opens it with that Python, and then everything above works the same way.
Arch Linux and CachyOS (a PC, or a Steam Deck running them)
The steps below are the same. First install what the build and the game use from pacman (Python with Tk, git, unzip, zenity for the game's name box and the Link Play choice, the Vulkan loader), then the Vulkan driver for your GPU:
sudo pacman -S --needed python tk git unzip zenity vulkan-icd-loader
sudo pacman -S --needed vulkan-radeon
(AMD, and the Steam Deck.) For an NVIDIA card (GTX 16xx and newer) instead:
sudo pacman -S --needed nvidia-utils
On KDE, kdialog works in place of zenity. Python's modules still go into the venv of step 2.
Steam Deck: build in Desktop Mode
Press the Steam button → Power → Switch to Desktop, then open Konsole (the terminal, in the application menu under System). Each step is one command; copy them as they are.
- Unzip the download into your home folder (Dolphin: right-click → Extract → Extract archive here), or:
bash
cd ~ && unzip ~/Downloads/Pokopia-Native-for-Linux.zip
- Python's modules, in a folder of their own (SteamOS keeps its system folders read-only, so they go into your home):
bash
python3 -m venv ~/pokopia-venv && ~/pokopia-venv/bin/pip install lz4 fonttools pillow zstandard
(zstandard reads .nup files; without it the builder uses the zstd command, which most Linux systems have.) Python 3.15 (python3 --version) has no ready-made lz4 package yet, so pip
builds lz4 itself and needs a C compiler first: sudo pacman -S --needed base-devel on Arch and CachyOS (build-essential python3-dev on
Debian and Ubuntu), then the same command again.
- The .NET 10 runtime (the shader translator), with Microsoft's own installer script, into
~/.dotnet:
bash
curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 10.0 --runtime dotnet
- Check and set up (setup fetches nxnative, the project's MIT base, with git):
bash
cd ~/pokopia-native-*/ && ~/pokopia-venv/bin/python nxs2.py doctor && ~/pokopia-venv/bin/python nxs2.py setup --no-ios
Every line of doctor should say ok. If one says MISSING, it says what to do; send me the output if it does not help.
- Build (replace the path with your dump's folder; the build folder goes beside it unless you add
--out <folder>):
bash
~/pokopia-venv/bin/python nxs2.py build ~/Games/Pokopia --linux
The long part is the recompile: about 30 to 45 minutes on a Steam Deck. The Deck stays usable; leave it plugged in. If the build stops, run the same command again: it continues where it was.
Play
~/Games/Pokopia_native/out/play-pokopia-2.0.1.sh
(the file is named after your game version: ls ~/Games/Pokopia_native/out/). A window opens first: how to play (alone, Link Play on your
network, or over the internet), the picture's basics (console mode, window or full screen, anti-aliasing, frame rate, the FPS counter) and
Check for updates. Where it cannot open (a Python without Tk), the same questions come as the desktop's dialogs or in the terminal. The first
start translates the shaders the game makes while it runs: for about a minute the ground and some menus may be white. That is expected. After
"ask again next time" is off, pokopia-settings-<version>.sh beside it brings the window back, then starts the game.
With the app, Play on its Home does all of this: it starts the same game with the choices made in the app (Link Play, Settings), so the window above doesn't show.
Updates: once a day the app (or the game's launcher) asks the website and GitHub for the latest release's version (two requests; nothing about you, the game or the computer is sent beyond what any web request carries). When a newer one is out, the app says so and Update now updates (above); the launcher says so in its window, or in a small window of its own beside the game when the window is not shown (in Steam's Game Mode, only a line in the terminal), and its Download opens the release page. With the zip, unzip the new one and run its build command again with the same build folder: only what changed is redone, and your save and settings stay.
Players online: while the app is open, the website counts it in players online now: the app sends a random number made new at
each start, whether you're playing, Linux or Steam Deck, and its version, and nothing else (LEGAL.md).
Settings → App → Players online on the website turns it off.
Check for updates (in the app: Settings → App) turns it off for the app and the launcher alike (it is "check": false in
~/.local/share/pokopia-native/updates.json).
- Controls: the Steam Deck's own controls work as a Switch controller (A/B/X/Y by position, the sticks, the triggers). Keyboard and mouse: WASD to move, the mouse to look (click the picture; Esc releases the mouse), J/K/U/I for A/B/X/Y, Return for +, Tab for −, F11 for full screen.
- Settings in the game: F1, or − and + together on a controller (the Steam Deck's View and Menu buttons, either side of the screen),
opens the settings over the game: the picture (Resolution, window or full screen, Upscaling, Anti-aliasing, 30 fps, Vsync, an FPS counter)
and the keyboard's keys. Changes apply at once (Console mode from the next start) and are kept in
~/.config/pokopia-native/for the next start. - On a Steam Deck the game starts in its handheld mode: its own lighter settings (about a quarter less graphics work). F1 → Console mode → Docked (TV) switches back from the next start, and that choice is kept.
- On a Steam Deck the game draws at the screen's own 1280x720, with FXAA: drawing 1920x1080 only to shrink it onto the screen costs about a quarter more graphics work for slightly smoother edges. F1 → Resolution and F1 → Anti-aliasing change it (1920x1080, SMAA), and that choice is kept.
- Your save:
~/.local/share/pokopia-native/<version>/save. To bring your save from Windows, a Mac or the phone: in the app, Saves and DLC → Bring a save from another device (the same page has Back up now, the backups and Restore), or~/pokopia-venv/bin/python nxs2.py import-save ~/Games/Pokopia_native <the folder with B00, G00 and S00>. The save that was there is kept beside it. - Your DLC: if you bought the game's DLC, give Pokopia Native your own dump of it, made the same way as your dump of the game: in
the app, Saves and DLC → Add my DLC (or Add my DLC after the first build), or
~/pokopia-venv/bin/python nxs2.py import-dlc ~/Games/Pokopia_native <your DLC folder>(its RomFS, or the folder holding it). It's copied into the build folder, and the game finds it from its next start. Only your own DLC: Pokopia Native never downloads, makes or unlocks DLC, and you should never share your DLC folder.
Game Mode (play from the Steam Deck's own interface)
With the app, Add to Steam (above) puts Pokopia Native in your library. In Game Mode the app opens full screen, made for the Deck's controls: the D-pad or the left stick moves, A chooses, B goes back, L1 and R1 go through the sections, and the Menu button plays. Link Play, Settings, Mods and Saves and DLC all work there; to type an address or a room code, Steam + X opens Steam's keyboard.
Without the app, in Desktop Mode, open Steam → Games → Add a Non-Steam Game to My Library → Browse, choose
~/Games/Pokopia_native/out/play-pokopia-<version>.sh, and add it. Back in Game Mode it is in your library under "Non-Steam". That
launcher shows no Link Play window in Game Mode: it plays the way you chose last time in Desktop Mode (alone the first time). To choose
there instead, open the game's Properties → Launch Options and put %command% --link-play (host) or %command% --join 192.168.1.20
(visit that address); add --story for Story co-op (below).
Your character's name (a new game asks for it once, and it cannot be changed later): a box comes up for it. If the box shows in Game Mode, Steam + X opens Steam's keyboard to type into it; tap OK on the screen when done. If no box shows, or you have only a controller, press A (or +) and the name is "Player". In Desktop Mode the same works, and a keyboard types into the box as usual. To choose the name yourself, start a new game in Desktop Mode.
Link Play
Linux plays Link Play with Windows PCs, Macs and iPhones that run the same pokopia-native version. Linux does not find hosts on its own network yet:
- you host: choose "host here"; the others pick this computer's address (
ip -4 addrshows it, for example 192.168.1.20). A Linux PC with a firewall (ufw,firewalld) must allow port 47600, TCP and UDP. SteamOS has no firewall. - you join: choose "join a host on this network by its address" and type the host's address.
- over the internet: as on Windows (docs/WINDOWS.md, "Playing together"): a room code, and the host's router forwards port 47600.
In the game: Link Play, then Local connection (not Online connection). Every player needs a save of their own.
Interact everywhere (visitors use moves and items and build in every town) and Story co-op (on top of it: visitors talk to the story
characters too) are experimental, and every player needs the same choice: the Link Play choice asks for both, or give --interact or --story
after the launcher's name. With both off, Linux plays with 1.2.x as well. They work on game versions 2.0.1 and 1.0.5; on 1.0.5 every
player needs pokopia-native 1.3.3 or newer.
Recording a problem
When something goes wrong, a recording of it helps more than any description.
- OBS Studio from Discover (the software centre) records the whole screen: start a recording, show what goes wrong, stop it.
- Or Spectacle (the screenshot tool), if your desktop's version has screen recording (Plasma 6).
- In Game Mode, Steam's own game recording (Steam → Settings → Game Recording) works too.
Please keep recordings short (a few minutes each) and do not record anything personal on the screen.
The game can record a problem for the report too: F1 (Minus + Plus on a controller) → Report. Record 60 seconds measures the next minute, frame by frame, while you play where it's slow; Capture what's on screen saves a picture of the game and the list of the graphics programs that drew it. The report takes the newest of each by itself, and the game's log notes every moment the sound drops out.
The report
When something goes wrong, open a terminal (Konsole on the Steam Deck) and run the report. With the AppImage (with more than one AppImage in
Downloads, put the one you use in full in place of Pokopia-Native-*.AppImage):
~/Downloads/Pokopia-Native-*.AppImage report
With the zip:
~/pokopia-native-*/linux/report.sh
It finds your build folder by itself (the app's last one, or one in your home folder or on an SD card) and says which one it took. To name
another, put its path after the command as it is, without < > around it: ~/pokopia-native-*/linux/report.sh /run/media/deck/MyCard/Pokopia.
It collects the game's logs (with the newest frame-time recordings and screen capture), the build's logs and facts about your computer (CPU, GPU, driver and Mesa version, SteamOS or distribution version,
memory, display) into one pokopia-report-<date>.tar.gz in your home folder, and its last line says where it is. It never includes your save, the game's files, shader files or your
dump, and it replaces your home folder, user name and computer name with placeholders. It lists every file and asks before it writes the archive,
so you can read them first.
Then fill in the Linux / Steam Deck report form on GitHub and attach that archive: the form asks the rest (your device, the build, the title screen and the game, controls, sound, saves). Screenshots and short recordings help too; a recording over 10 MB goes in as a link. No GitHub account? Send me the same answers and the archive directly.
Common problems
- "out of memory mappings" or a crash after a while: some distributions allow few memory mappings per process. SteamOS allows many. Elsewhere:
sudo sysctl vm.max_map_count=1048576(and in/etc/sysctl.d/to keep it). - No window, or "no Vulkan loader": install your distribution's Vulkan loader and Mesa Vulkan drivers (
vulkan-icd-loaderandvulkan-radeonon Arch,libvulkan1andmesa-vulkan-driverson Debian and Ubuntu). doctorsays the CPU lacks AVX2: the recompiled game needs it; that CPU cannot run it.- The game closes by itself, or the picture breaks up, when a new place loads: start it once with the driver's bounds checks on and say in the
report whether that helped:
NXRT_VK_ROBUST=1 ~/Games/Pokopia_native/out/play-pokopia-2.0.1.sh - Bright sparkles on characters' edges (seen on Intel graphics): the picture is drawn at an uneven size for your screen (the log says "resolution x1.11111", for example). A 16:10 screen such as 1920x1200 gets the game's own 1920x1080 by default, which fits it exactly. If you chose a size yourself, F1 → Resolution → 1920x1080 (the game's own) or 3840x2160 (exactly twice) avoids it. Thanks to Apocal for finding it.
- AMD or Intel graphics: freezes, or flashes near a campfire: the game's graphics programs were written for groups of 32 (NVIDIA's); AMD
runs 64 and Intel 8 to 32. Since 1.5.0 the game asks for 32 wherever the driver allows it (newer AMD cards, the Steam Deck, Intel); the log
says "made with 32 lanes" and for which stages. If something looks worse than in 1.4.1, start the game once without it and say in the report
which was better:
NXRT_VK_SUBGROUP32=0 ~/Games/Pokopia_native/out/play-pokopia-2.0.1.sh. - The build stops with "shorter than its own header says": the dump's
exefswas copied in text mode; copy it again in binary mode. - The frame rate swings on a Steam Deck and it feels laggy: in the game, F1 → Frame rate → 30 fps gives a steady 30 instead. Since
1.4.0 the Deck starts in the game's handheld mode (F1 → Console mode → Docked (TV) switches back), and our graphics work runs on a thread of
its own beside the game's (
NXRT_REPLAY_THREAD=0in front of the launcher turns that off, to compare). On an OLED Deck, set the screen to 60 Hz in the Quick Access menu's Performance page: the game's 60 fps does not divide evenly into 90 Hz. A report after 5 minutes in your town (below) shows us where the time goes. - The sound crackles or stutters: the game plays through SDL's PulseAudio driver first (PipeWire answers it too, through pipewire-pulse),
which fixed the stutter players heard through SDL's own PipeWire driver. If it still crackles, try the others once and say in the report which
helped:
SDL_AUDIO_DRIVER=pipewire ~/Games/Pokopia_native/out/play-pokopia-2.0.1.sh(oralsa). The log'saudio: SDL ..., audio driverline names the driver in use, and itsaudio #0 device callbackslines count the underruns. A fast flutter or tremolo in the sound (as if it shook about 47 times a second) was the game's own mixer falling behind when the sound server took several blocks at once; the game now hands those blocks back about 1 ms apart.NXRT_AUDIO_RELEASE_GAP_US=0turns that off, and2000gives the mixer more time.