Distributing Your Ren'Py Game: From Build to itch.io

Your game is done. The next step is getting it into players' hands.

This guide covers how to build your game in Ren'Py 8.5.2 and publish it on itch.io.

Preparing for Build

options.rpy Settings

Set basic build information in options.rpy. A template is generated when you create a project — just update the values.

define config.name = "My Visual Novel"

define build.name = "MyVisualNovel"

define config.version = "1.0"

config.name is your game's title. build.name is used for distribution filenames — no spaces, colons, or semicolons allowed. config.version is the version number, also referenced when uploading to itch.io.

Running Lint

Always run Lint before building. Click "Check Script (Lint)" in the Launcher.

Lint checks for:

• References to undefined images or characters
• Unreachable labels
• Missing audio files
• Other potential issues

Fix any errors before proceeding. Warnings aren't critical but should be resolved when possible.

Changing the Icon

Replace the default Ren'Py icon with your own.

mygame/               ← Base directory (place icons here)
├── icon.ico          ← Windows (256x256 recommended)
├── icon.icns         ← macOS
└── game/
    └── ...

Place them in your project's base directory (the parent of game/).

Running the Build

Building from the Launcher

1. Select your project in the Ren'Py Launcher
2. Click "Build Distributions"
3. Select which packages to build (all platforms are selected by default)
4. When the build completes, the output folder opens

Output Files

With default settings, these files are generated:

The pc package includes executables for both Windows and Linux. Players just run the one for their OS.

Platform-Specific Notes

Windows

No special setup needed. Extract the zip and double-click the .exe. The easiest platform.

macOS — The Gatekeeper Problem

macOS restricts unsigned applications. Since macOS Sequoia (15.0), these restrictions have gotten stricter.

To launch an unsigned game, players need to run this in Terminal:

xattr -r -d com.apple.quarantine /path/to/MyVisualNovel.app

Linux

Run the .sh file included in the pc package. If it lacks execute permission, run chmod +x first.

Android

Android builds use RAPT (Ren'Py Android Packaging Tool).

1. In the Launcher, go to "Android" → "Install SDK"
2. JDK 21 (Adoptium recommended) is required
3. "Generate Keys" to create signing keys (back these up)
4. "Configure" to set package name, icon, etc.
5. "Build" to generate an APK or AAB

Use AAB (Android App Bundle) for Google Play, APK for direct distribution.

Web (Beta)

You can build a browser-playable version too.

1. In the Launcher, go to "Web (Beta)" → "Build Web Application"
2. Open index.html in the output folder to test

Web builds are ideal for "Play in browser" on itch.io, but large file sizes mean longer load times. Optimize your images and audio.

Publishing to itch.io

Manual Upload

1. Create an account on itch.io
2. Go to Dashboard → "Create new project"
3. Fill in project details (title, description, tags, etc.)
4. Set "Kind of project" to "Downloadable"
5. Upload your built zip files
6. Set platform tags (Windows / macOS / Linux) for each file
7. Click "Save & view page" to publish

For web builds, set "Kind of project" to "HTML", upload the zip, and check "This file will be played in the browser".

Auto-Upload from the Launcher

Add this to options.rpy to upload directly from the Launcher:

define build.itch_project = "username/project-name"

After building, an "Upload to itch.io" button appears. First-time use will prompt you to install and log into itch's CLI tool (butler).

Auto-upload maps files to itch.io channels based on filename patterns:

Controlling Files with build.classify()

Default build settings work for most cases, but use build.classify() when you need to exclude files or customize archiving.

Excluding Development Files

init python:
    # Exclude Photoshop and illustration source files
    build.classify("**/*.psd", None)
    build.classify("**/*.clip", None)

    # Exclude development notes
    build.classify("**/TODO.txt", None)

Setting None excludes files matching the pattern from the build.

Archiving Files

Bundle images and audio into .rpa archives to reduce file count. This helps with itch.io's 1000-file limit for web builds.

init python:
    build.classify("game/**.png", "archive")
    build.classify("game/**.jpg", "archive")
    build.classify("game/**.ogg", "archive")

Pattern Syntax

Patterns are evaluated top to bottom — the first match wins. Put more specific patterns first.

Wrapping Up

What we covered:

• Build preparation: options.rpy settings, Lint check, icon replacement
• Running the build: A few clicks in the Launcher to generate zip files
• Platform notes: macOS Gatekeeper issues, Android signing key management, web build file size
• Publishing to itch.io: Manual upload and auto-upload from the Launcher
• build.classify(): Excluding dev files, archiving, and the # prefix trick

For Ren'Py basics, see the getting started guide.

Official resources:

• Building Distributions — official build reference
• Android — Android build details
• Web — web build details
• itch.io — indie game distribution platform
• r/RenPy — community