I parsed Steam's binary shortcuts.vdf with zero dependencies

I have a Steam Deck and a pile of self-contained Linux games — Godot exports, LÖVE builds, the odd plain ELF — that aren't on Steam. Getting one of them to show up in Game Mode as a proper library tile, with box art, controller-ready, is more fiddly than it should be. So I wrote a small tool to do the boring parts for me, and the most interesting part of building it turned out to be the file format Steam uses to track non-Steam games.

This is a writeup of that part: reading and rewriting shortcuts.vdf, why I did it with nothing but the Python standard library, and a couple of gotchas that cost me time so they don't cost you any.

Quick honesty note up front, because it shapes everything below: this is a side project. The format parsing is tested for clean round-trips, but I have not confirmed the full pipeline end to end on real Deck hardware yet. Treat the code as "interesting and worth poking at," not "battle-tested." Repo is at the bottom.

The actual problem

When you "Add a Non-Steam Game," Steam doesn't write a config file you can comfortably hand-edit. It records the entry in shortcuts.vdf, a binary file in Valve's KeyValues format, sitting in your userdata directory. If you want a game to appear without clicking through the UI, you have to write a valid entry into that binary file yourself.

And there are three smaller problems hiding behind that one:

1. The game's executable bit gets stripped the moment you copy it over SFTP or SMB. A Linux game with no +x silently refuses to launch, and it's the single most common reason a copied-over game looks broken.
2. The artwork (capsule, hero, logo) has to be named after an app ID that Steam computes internally — so you can't just drop in cover.jpg and hope.
3. SteamOS's root filesystem is immutable, which quietly rules out a whole category of "just pip install it" solutions.

That third one is what makes the design fun.

Why zero dependencies

The obvious move is to grab an existing VDF library off PyPI and move on. But the script's home is the Deck itself, and SteamOS mounts its root read-only. Installing pip packages onto it is a fight you don't want to have on a device that wipes changes outside /home on every system update.

So the constraint became a feature: the thing that runs on the Deck imports nothing outside the standard library. No vdf, no requests, no pillow. struct, zlib, os, shutil — that's the toolbox. The upside is a single file you copy over and run with python3, with nothing to install and nothing to break after an OS update.

To keep that honest as the code grew, the importer lives as a normal package during development and a build script flattens it into one file, with CI checking two things: that the flat file stays in sync with the package, and that it imports nothing outside stdlib. If someone adds import requests to the Deck-side code, the build fails.

Reading the binary KeyValues format

shortcuts.vdf is Valve's binary KeyValues. Once you've stared at a hex dump for a while it's actually a tidy little format. Every value is introduced by a one-byte type tag:

• 0x00 — start of a nested object (a map). A null-terminated key name follows, then the object's contents.
• 0x01 — a string. Null-terminated key, then a null-terminated UTF-8 value.
• 0x02 — a 32-bit little-endian integer. Null-terminated key, then four bytes.
• 0x08 — end of the current object.

The whole file is one top-level map named shortcuts, whose children are "0", "1", "2", … — one numbered object per game. Each game object is a flat bag of fields: appid (an int), AppName, Exe, StartDir, LaunchOptions (strings), and a nested tags map for collections.

Parsing it is a small state machine: read a type byte, read a null-terminated key, then dispatch on the type to read a string, an int, or recurse into a nested map, until you hit 0x08. Writing it back is the same walk in reverse. Nothing exotic — but it is unforgiving, because one misplaced byte and Steam treats the file as corrupt.

The rule that kept me sane: byte-identical round-trips

The scariest thing about rewriting a file Steam owns is clobbering shortcuts the user already has. So before adding a single feature, I made the parser pass one test: read a real shortcuts.vdf and write it back out byte-for-byte identically. If I can't reproduce the input exactly, I don't understand the format well enough to be editing it.

That round-trip test is the backbone of the whole thing. Adding a new entry then becomes "parse the existing structure, append one object, serialize" — and because serialization is proven faithful, the existing entries come out untouched. The tool also backs the file up before writing, but the real safety is that the write path is boring and verified rather than clever.

Detecting the game binary

A dropped game folder is a mess of files: the executable, shared objects, data packs, maybe a readme. Picking the right binary to launch is a small heuristic:

• Read the first bytes and check for the ELF magic (\x7fELF). No magic, not a candidate.
• Skip shared objects (.so), because a library is not a game.
• Score what's left. A Godot *.x86_64 export wins easily. Failing that, prefer a bare-named ELF, or one whose name resembles the folder, or — last resort — the largest executable, on the theory that the game is usually the biggest binary in the box.

Then chmod 0755 it, because of that stripped execute bit from earlier. This one line fixes the most common "why won't my game start" complaint before it happens.

The neat trick: one ID names everything

Here's the detail that makes the two halves of the tool — a PC side that fetches artwork, a Deck side that registers the game — work without having to coordinate.

Steam keys both a non-Steam shortcut and its artwork off a single app ID. So if you can compute that ID deterministically, you can name the art files correctly before Steam ever sees them. The ID is derived from the executable path and the game name:

import zlib

def shortcut_appid(exe: str, name: str) -> int:
    return zlib.crc32((exe + name).encode("utf-8")) | 0x80000000

That | 0x80000000 sets the high bit, landing the number in the range Steam reserves for non-Steam shortcuts. Because it's deterministic, the same integer that goes into shortcuts.vdf also names the grid art:

shortcuts.vdf  appid = 3580912219
config/grid/   3580912219p.jpg      (portrait capsule)
               3580912219.jpg       (landscape grid)
               3580912219_hero.jpg  (hero banner)
               3580912219_logo.png  (logo)

So the PC side never needs to know the Deck's file paths or the final ID. It ships generically named art (cover, hero, logo), and the Deck computes the ID once and renames everything to match. This deterministic-ID approach isn't something I invented — it's the same pattern Steam ROM Manager and SteamTinkerLaunch rely on, which is exactly why Steam honors a hand-written app ID and matches the artwork to it.

Gotchas that cost me time

A few things that are not in any obvious place and that I'd want a past version of myself to know:

• Steam must be closed when you write the file. Steam holds shortcuts.vdf in memory and rewrites it on exit, so any edit you make while it's running gets silently wiped on shutdown. The tool refuses to run if Steam is up. Restart Steam afterward to pick up both the new shortcut and the new art.
• You can't precompute steam://rungameid/<id> anymore. Valve randomized the Big Picture launch ID per-add, so the old trick of building a launch URL ahead of time is dead. The way around it is to not need it: you launch by tapping the tile in Game Mode, not via a URL.
• SteamOS updates wipe everything outside /home. Enabling SSH and setting a password live on the immutable root and can be reverted by an update. Your games, your shortcuts.vdf, and your grid art all live in /home and survive — but you may have to re-enable SSH once after a big update.
• Removing a game leaves orphans. Steam doesn't clean up a removed shortcut's shortcuts.vdf entry, its compat-tool mapping, or its grid art. Cleanup is on me, not on Steam.

What I deliberately didn't build

The tool's lane is native Linux games, where it's genuinely lightweight. For Windows games I stopped short on purpose. Recreating a Windows environment — Wine/Proton prefixes, DirectX and Visual C++ redistributables, per-game fixes — is an enormous, already-well-solved problem owned by Lutris and Bottles. Reimplementing that badly would help no one. At most the tool writes the Proton compatibility-tool mapping and defers the hard part to the tools that do it well.

Knowing where to not extend a side project is, I think, underrated.

Takeaways

The thing I keep coming back to is that the immutable-filesystem constraint, which felt like an obstacle, produced the cleanest design decision in the project: no dependencies, one file, verified-faithful serialization. The interesting work wasn't a framework — it was understanding a binary format well enough to reproduce it exactly, and finding the one deterministic ID that let two separate halves agree without talking to each other.

If you want to look at the code, pick holes in the VDF handling, or — especially — try it on an actual Deck and tell me what breaks, the repo is here:

https://github.com/wesellis/deckport

And the recipe book / project site:

https://wesellis.github.io/deckport/

Feedback and corrections welcome. It's a hobby project and it improves fastest when someone who knows this corner of Steam better than I do points out what I got wrong.