Skip to content
Universal Modder Guides

setup / requirements

Check Universal Modder requirements before installing

Quick answer

Check the required software tools before using universal-modder, including Python 3.10+, uv, ffmpeg, and optional Blender for 3D sprite rendering. The toolchain software is free and open source; using AI coding assistants may require subscriptions or API billing, and fal asset generation is a separate paid service.

Prerequisites

  • A single-player PC game you legally own, within the usage boundary below.
  • Python 3.10 or later installed on your system.
  • uv package manager installed for tool orchestration.
  • ffmpeg installed and accessible on PATH for video recording and editing.
  • Blender installed if you need to render 3D models into 2D sprites.
  • Windows 10/11 with winget, or WSL for Linux-based mod workflows.
  • A dedicated mod working directory (such as C:\mods).

Steps: check and install Universal Modder requirements

  1. Check baseline cross-platform tools

    What to do

    Open a terminal in your mod working folder. Check if Python 3.10+, uv, and ffmpeg are installed and accessible on your PATH.

    Command

    Command
    python --version
    uv --version
    ffmpeg -version

    What you should see

    Each tool outputs its installed version number. Python must report version 3.10 or newer.

    If something goes wrong

    If any tool is missing, install it using your platform’s package manager or follow the dedicated Windows steps below.

  2. Windows installation with winget and WSL

    What to do

    For Windows users, install all required components one by one using the built-in winget package manager. Windows games are driven natively or from WSL.

    Command

    Windows terminal:

    Command
    winget install Python.Python.3.12
    winget install astral-sh.uv
    winget install Gyan.FFmpeg
    winget install BlenderFoundation.Blender

    What you should see

    winget downloads and installs each package. Restart your terminal after installation so your environment PATH updates.

    If something goes wrong

    If winget is not recognized, ensure Windows App Installer is installed from the Microsoft Store, or run Windows Terminal as Administrator. If using WSL, install packages inside your Linux distribution using apt or uv.

  3. Install Blender for 3D sprite rendering

    What to do

    Blender is optional and only required if you want the agent to render 3D models into game-ready sprites or isometric frames.

    Command

    On Windows:

    Command
    winget install BlenderFoundation.Blender

    Check version:

    Command
    blender --version

    What you should see

    Blender reports its installed version number.

    If something goes wrong

    If you do not plan to generate 3D models or render 3D-to-sprite assets, you can skip installing Blender entirely.

  4. Create a dedicated mod working folder

    What to do

    Create a separate project directory for your mods, such as C:\mods on Windows or ~/mods on macOS/Linux. Never work directly inside game installation folders.

    Command

    Windows:

    Command
    mkdir C:\mods
    cd C:\mods

    macOS or Linux:

    Command
    mkdir -p ~/mods
    cd ~/mods

    What you should see

    The directory is created and you are located in the clean working folder.

    If something goes wrong

    Ensure your user account has write permissions to the created folder.

  5. Verify the um CLI availability

    What to do

    The um CLI is installed automatically with agent plugins or clones. If you are using plain skills or a standalone setup, install um globally with uv.

    Command

    Command
    uv tool install git+https://github.com/rehan-remade/universal-modder
    um --help

    What you should see

    The help menu lists available command groups: scan, fal, sprite, render3d, win, video, backup, publish, and kb.

    If something goes wrong

    If uv fails to install the tool, you can alternatively install via pipx with pipx install git+https://github.com/rehan-remade/universal-modder.

Verify it worked

  • Confirm that python --version returns 3.10 or higher.
  • Confirm that uv --version and ffmpeg -version return valid outputs.
  • If using Blender, confirm that blender --version outputs its version.
  • Confirm that your dedicated mod folder is separate from game install directories.
  • Run um --help to confirm that the CLI commands are accessible.

FAQ

What are the minimum requirements for Universal Modder?

You need a legally owned single-player PC game, Python 3.10 or later, ffmpeg for video capture and editing, and uv for Python dependency management. Blender is only needed for 3D-to-sprite rendering.

Can I run Universal Modder on Windows?

Yes. Windows games are driven natively or from WSL. Windows users can install all required tools with four winget commands in PowerShell: Python 3.12, uv, ffmpeg, and Blender.

Is Blender required to mod games?

No. Blender is only required if you want the agent to convert 3D models into game-ready sprites or isometric frames. Pure code mods, texture edits, and save manipulation do not require Blender.

What should I do if winget commands fail on older Windows 10 builds?

Update the App Installer package from the Microsoft Store, which supplies the winget CLI. Alternatively, you can download standalone installers directly from the official websites for Python, uv, ffmpeg, and Blender.

How do I verify that ffmpeg and uv are accessible in any terminal?

Open a fresh terminal window and run uv --version and ffmpeg -version. If either returns a command not found error, open Windows System Properties, inspect your Environment Variables, and add their installation directories to your PATH.