https://github.com/ikajdan/steammetadatatool
A tool for managing Steam client game metadata and library artwork
https://github.com/ikajdan/steammetadatatool
appinfo metadata metadata-editor pyside6 python steam steam-client steam-games vdf-parser
Last synced: 1 day ago
JSON representation
A tool for managing Steam client game metadata and library artwork
- Host: GitHub
- URL: https://github.com/ikajdan/steammetadatatool
- Owner: ikajdan
- License: gpl-3.0
- Created: 2026-04-26T19:10:07.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-06T13:04:26.000Z (22 days ago)
- Last Synced: 2026-06-06T15:07:04.576Z (22 days ago)
- Topics: appinfo, metadata, metadata-editor, pyside6, python, steam, steam-client, steam-games, vdf-parser
- Language: Python
- Homepage:
- Size: 539 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
SteamMetadataTool
Overview •
Screenshots •
Installation •
Usage •
Editing •
Translating •
License
SteamMetadataTool is a desktop and command-line utility for inspecting and customizing game metadata used by the Steam client. It can browse installed apps, export metadata, and apply local overrides without replacing the original workflow.
- List app IDs and game names from a local Steam installation.
- Export app records as JSON for inspection or backup.
- Edit names, sort-as values, aliases, release dates, and other metadata fields.
- Set custom Steam library artwork, including capsules, headers, heroes, logos, and icons.
- Preview, save, and apply metadata overrides.
The GUI provides a searchable app list, metadata filtering, app detail preview, and dialog for editing metadata values. It also shows Steam library assets and supports choosing between original and custom artwork variants from per-app asset folders.
> [!NOTE]
> This tool is not affiliated with Valve Corporation or Steam.
>
> Steam is a registered trademark of Valve Corporation and is referenced solely for descriptive purposes.
## Screenshots
## Installation
The tool is split into two components: a CLI and a GUI.
### CLI
To install the CLI only:
```bash
uv sync
```
### GUI
To install the GUI and CLI together:
```bash
uv sync --extra gui
```
## Usage
### CLI
List apps:
```bash
uv run steammetadatatool-cli
```
Dump an app as JSON:
```bash
uv run steammetadatatool-cli --appid 10 --json | python -m json.tool
```
### GUI
To use the windowed GUI:
```bash
uv run --extra gui steammetadatatool-gui
```
#### Library Assets
Steam library assets are images that represent games in the Steam library. Each asset type has specific size requirements:
| Asset | Required size |
| ------- | ------------------------------- |
| Capsule | 600 px by 900 px |
| Header | 920 px by 430 px |
| Hero | 3840 px by 1240 px |
| Logo | 1280 px wide and/or 720 px tall |
| Icon | 184 px by 184 px |
The full specification can be found at: .
> [!TIP]
> Steam Library asset changes might not refresh immediately in the Steam client.
> If updated artwork does not appear right away, switch to another game and back,
> or restart the Steam client.
## Editing
Apply per-app metadata overrides:
```bash
uv run steammetadatatool-cli \
--appid 10 \
--name "Counter-Strike 1.6" \
--sort-as "cs" \
--aliases "cs, 16" \
--steam-release-date 2000-11-08
```
Dry-run (no write):
```bash
uv run steammetadatatool-cli \
--appid 10 \
--name "Counter-Strike 1.6" \
--dry-run
```
Write metadata overrides to a JSON file:
```bash
uv run steammetadatatool-cli \
--appid 10 \
--name "Counter-Strike 1.6" \
--metadata-file metadata.json
```
Apply metadata overrides from a JSON file for a specific app:
```bash
uv run steammetadatatool-cli \
--metadata-file metadata.json \
--appid 10
```
Apply metadata overrides from a JSON file for all apps:
```bash
uv run steammetadatatool-cli \
--metadata-file metadata.json
```
Write changes without creating a backup:
```bash
uv run steammetadatatool-cli \
--appid 10 \
--name "Counter-Strike 1.6" \
--no-backup
```
Set arbitrary KV path:
```bash
uv run steammetadatatool-cli \
--appid 10 \
--set appinfo.common.sortas="cs" \
--set appinfo.common.original_release_date=946684800
```
### Write to a new file
```bash
uv run steammetadatatool-cli \
--appid 10 \
--name "Counter-Strike 1.6" \
--aliases "cs, 16" \
--write-out /tmp/appinfo.vdf
```
## Translating
Translations are managed with gettext files under `data/i18n`. After changing
user-facing strings, refresh the template:
```bash
./tools/manage-translations.sh extract
```
Start a new locale from the template, using a gettext locale name such as `pl_PL`:
```bash
./tools/manage-translations.sh init LOCALE
```
Update existing `.po` files after source string changes:
```bash
./tools/manage-translations.sh update
```
Compile translations before testing or packaging. This writes `.mo` files and
refreshes translated desktop and metainfo entries:
```bash
./tools/manage-translations.sh compile
```
## License
This project is licensed under the GNU General Public License version 3 or later. See the [LICENSE](LICENSE.md) file for details. The application logo is not covered by the GNU GPL v3 or later and may not be used without prior permission.