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

To distribute a Ren'Py game, you build platform packages from the Launcher (Windows/macOS/Linux/Android/Web), then upload the zip files to itch.io — either manually or via the built-in butler integration. The whole process takes minutes once your options.rpy is configured.

This guide covers the full workflow using Ren'Py 8.5.2: build preparation, platform-specific gotchas, itch.io publishing, and file control with build.classify().

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 Temurin 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. See the official Android build docs for full details on configuration and troubleshooting.

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. itch.io enforces a 1000-file limit and 500 MB total size cap for browser games. Optimize your images and audio, and use build.classify() to archive assets into .rpa files (covered below). See the official Web build docs for platform limitations.

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.

FAQ

Can I distribute my Ren'Py game on Steam?

Yes. Ren'Py supports Steam integration through Steamworks. You'll need a Steamworks developer account ($100 one-time fee), and you configure Steam-specific settings in options.rpy. The build process is similar — you generate distribution files and upload them via Steam's tools.

Do I need to sign my game for Windows?

Not strictly required. Windows SmartScreen may show a warning for unsigned executables, but players can click "More info" → "Run anyway." Code signing certificates cost $200–400/year, so most indie developers skip it. The warning typically goes away once enough users have downloaded your game.

How do I update my game on itch.io after release?

Upload new builds with the same channel names. If you're using butler, just run the push command again — butler handles delta patches automatically, so returning players only download what changed. For manual uploads, replace the files on your project page.

Can I build for iOS?

Ren'Py doesn't officially support iOS builds. Some developers have used third-party tools or Xcode workarounds, but it's not a supported workflow. Focus on Android for mobile distribution.

What's the difference between build.classify() targets "all", "windows", "linux", "mac"?

These targets control which platform packages include a file. "all" includes the file in every package. "windows" only includes it in the Windows build. You can combine them with spaces: build.classify("README.txt", "windows linux mac"). See the official build docs for the full list.

How large can my game be for itch.io?

For downloadable games, itch.io allows up to 1 GB per file (you can request more). For browser-playable HTML5 games, the limit is 500 MB total with a maximum of 1000 files. Use .rpa archives and optimize assets to stay within limits.

My macOS build shows "app is damaged" — what do I do?

This is the Gatekeeper quarantine flag. Run xattr -r -d com.apple.quarantine /path/to/YourGame.app in Terminal. If you're distributing to others, document this in your README. For a permanent fix, consider the Apple Developer Program ($99/year) and use Ren'Py's mac-notarization tool.

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. For choices and branching, see the choices guide. For adding BGM and sound effects, see the audio 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

Related articles:

• Getting Started with Ren'Py 8.5: From Install to First Build
• Ren'Py Screen Language: Custom UI from Scratch
• Ren'Py Image Basics: Formats, Sizes, and Optimization
• Ren'Py Stat Management: Design Patterns That Don't Break Saves
• Ren'Py Audio Guide: Music, Sound Effects, and Voice
• Can You Use Non-ASCII Filenames in Ren'Py?