game-install-finder 0.2.1

Find local game install paths across Steam, Heroic, and Lutris.

game-install-finder

Find local game install paths across PC game launchers. Supports Steam, Heroic, and Lutris.

game-install-finder discovers local launcher libraries, enumerates installed games, and resolves game install paths by launcher metadata. It currently reads Steam VDF/ACF metadata, Heroic, Legendary, sideload, and store-cache JSON, and Lutris pga.db metadata. The tool only reads local files and does not call any game store or launcher web API.

Features

• Detects Steam, Heroic, and Lutris on Windows, Linux, and macOS where local launcher metadata is available.
• Parses Steam libraryfolders.vdf with the vdf package instead of brittle string splitting.
• Includes games from primary and secondary Steam libraries.
• Reads Steam appmanifest_*.acf files to report appid, name, install directory, manifest path, and resolved local game path.
• Reads Heroic/Legendary installed.json, Heroic sideload, Heroic store-cache metadata, and Lutris pga.db installed-game metadata.
• Supports exact Steam appid lookup and fuzzy installed-game name matching across launchers.
• Emits machine-readable JSON, with optional pretty printing.
• Keeps project virtualenvs and tool caches under /tmp/game-install-finder through ./run.sh.

Installation

Install project dependencies with uv through the repository wrapper:

./run.sh uv sync

The wrapper configures the project virtual environment and caches outside the repository:

UV_PROJECT_ENVIRONMENT=/tmp/game-install-finder/.venv
XDG_CACHE_HOME=/tmp/game-install-finder/.cache
PYTHONPYCACHEPREFIX=/tmp/game-install-finder/__pycache__
TMPDIR=/tmp/game-install-finder

Usage

Run the CLI from the repository root:

./run.sh uv run game-install-finder --help

List installed games:

./run.sh uv run game-install-finder --list-games --pretty

Print the detected Steam installation path:

./run.sh uv run game-install-finder --steam-path --pretty

Use an explicit Steam root instead of auto-detection:

./run.sh uv run game-install-finder --steam-root PATH --list-games --pretty

Use explicit Heroic or Lutris metadata roots instead of auto-detection:

./run.sh uv run game-install-finder --heroic-root PATH --lutris-root PATH --list-games --pretty

Limit list or fuzzy search results to one launcher:

./run.sh uv run game-install-finder --launcher heroic --appid-from-name NAME --pretty

Find an installed Steam game by appid:

./run.sh uv run game-install-finder --app-id APPID --pretty

Fuzzy match an installed game name:

./run.sh uv run game-install-finder --appid-from-name NAME --pretty

Enable non-fatal parser and discovery warnings:

./run.sh uv run game-install-finder --list-games --debug --pretty

CLI Options

--steam-path            Return detected Steam installation path
--steam-root PATH       Use this Steam installation path instead of auto-detection
--heroic-root PATH      Use this Heroic or Legendary config path instead of auto-detection
--lutris-root PATH      Use this Lutris data path instead of auto-detection
--list-games            Enumerate installed games
--launcher LAUNCHER     Filter installed games by launcher
--app-id APPID          Lookup installed game by appid
--appid-from-name NAME  Fuzzy match installed game name to appid
--pretty                Pretty-print JSON output
--debug                 Print non-fatal parser/discovery warnings to stderr

JSON output

All successful commands include steam_path. Additional fields depend on the selected lookup.

--list-games adds games, an array of records shaped like:

{
  "appid": "730",
  "launcher": "steam",
  "name": "Counter-Strike: Global Offensive",
  "installdir": "Counter-Strike Global Offensive",
  "path": "/home/user/.local/share/Steam/steamapps/common/Counter-Strike Global Offensive",
  "exists": true,
  "source": "/home/user/.local/share/Steam/steamapps/appmanifest_730.acf",
  "library": "/home/user/.local/share/Steam",
  "manifest": "/home/user/.local/share/Steam/steamapps/appmanifest_730.acf"
}

--app-id APPID adds:

{
  "game": {
    "appid": "730",
    "launcher": "steam",
    "name": "Counter-Strike: Global Offensive"
  },
  "app_path": "/home/user/.local/share/Steam/steamapps/common/Counter-Strike Global Offensive"
}

Heroic and Lutris records use the same shape and include launcher, name, path, exists, and source; Steam-only fields such as library, manifest, and installdir are null when they do not apply. Heroic discovery reads installed.json, sideload_apps/library.json, and store_cache/{gog,legendary,nile}_library.json. Sideload entries resolve absolute folder_name values directly, relative folder_name values under defaultSettings.defaultInstallPath, and install.executable values to their parent directory.

--appid-from-name NAME adds match, candidates, and score. By default it searches Steam, Heroic, and Lutris records; use --launcher to narrow the search. If no confident fuzzy match is found, match is null and candidates still lists the closest installed game names.

Errors are emitted as JSON and return a non-zero exit code:

{
  "error": "Steam installation not found"
}

Dependency requirements

• Python 3.12 or newer for this project.
• uv for dependency management, packaging, and command execution.
• Runtime dependency: vdf, used to parse Steam VDF and ACF metadata.
• Heroic metadata is parsed with the Python standard library json.
• Lutris metadata is parsed with the Python standard library sqlite3.
• Development tools: pytest, pytest-cov, ruff, and ty.

Development

Run all project commands through ./run.sh:

./run.sh uv run ruff check . --fix
./run.sh uv run ruff format .
./run.sh uv run ty check src/
./run.sh uv run pytest

Build the package with uv:

./run.sh uv build --no-sources

The repository follows the local agent protocol in AGENTS.md: plans live under docs/plans/, tests must precede implementation changes, and generated caches must stay outside the repository.

Publishing

PyPI publishing is configured for GitHub Actions Trusted Publishing. The PyPI project should be configured with:

• Project name: game-install-finder
• Owner: beallio
• Repository name: game-install-finder
• Workflow name: workflow.yml
• Environment name: pypi

Release by pushing a version tag after the GitHub repository and PyPI Trusted Publisher are set up:

git tag -a v0.1.0 -m v0.1.0
git push origin v0.1.0

License

MIT - See LICENSE for details.