While building a game in Ren'Py, you might notice something.
play music "戦闘BGM.ogg"
A Japanese filename. No errors. It just works.
You might think "Great, I'll use native-language filenames for easier management." But the short answer is: don't. This guide explains why it works, why it's risky, and what to do instead.
The Short Answer: It Works, But It's Unofficial
In Ren'Py 8.5.2, using non-ASCII characters (Japanese, Chinese, Korean, accented Latin, etc.) in image, audio, and video filenames works on most systems.
However, this is not an officially supported feature. Tom Rothamel (PyTom), Ren'Py's creator, has consistently stated on the Lemma Soft Forums:
Use ASCII in all filesystem object names. This makes distribution and cross-platform compatibility significantly easier.
The official documentation contains no statement that Unicode filenames are supported.
Why It Works: Python 3 Unicode Handling
Understanding why non-ASCII filenames work requires a quick history lesson about Python.
The Python 2 Era (Ren'Py 6.x / 7.x)
In Python 2, strings were byte sequences (str = bytes) by default. To handle non-ASCII text, you needed the u"" prefix to explicitly create a Unicode string.
# Python 2 — this is a byte string
"battle_bgm.ogg"
# Python 2 — this is a Unicode string
u"戦闘BGM.ogg"
In Ren'Py 6.x, audio file handling passed filenames to C functions as char*, causing UnicodeEncodeError crashes with non-ASCII names. This was fixed in 2014, but Python 2's string handling remained fundamentally limited.
The Python 3 Era (Ren'Py 8.x)
In Python 3, strings are Unicode by default.
# Python 3 — this is already Unicode
"戦闘BGM.ogg"
The u"" prefix is no longer needed. Every string literal is natively Unicode. Ren'Py 8.x runs on Python 3.12, so the encoding issues from the Python 2 era simply don't occur at the string level.
In other words, Ren'Py didn't add non-ASCII filename support — Python 3 made Unicode the default, and filenames started working as a consequence.
Why It's Risky: Three Ways Distribution Breaks
Working on your dev machine and working on a player's machine are two different things. Non-ASCII filenames hit three landmines during distribution.
Case 1: macOS Unicode Normalization
macOS filesystems apply Unicode normalization to filenames. The legacy HFS+ stored names in NFD (decomposed form), and while the modern APFS preserves the original form on disk, it still performs normalization-insensitive comparisons under the hood. Windows and Linux typically use NFC (composed form) and match filenames byte-for-byte.
For example, the Japanese character "が" has two internal representations:
| Form | Representation | Description |
|---|---|---|
| NFC | が (1 character) | Composed. Standard on Windows/Linux |
| NFD | か + ゙ (2 characters) | Decomposed. Standard on macOS HFS+ |
A file stored as NFC 戦闘BGM.ogg in a ZIP may be normalized differently on macOS. When Ren'Py searches for the exact NFC byte sequence, the file isn't found because the filesystem sees a normalization-equivalent but byte-different name.
This exact problem was reported in the commercial Ren'Py game "WORLD END ECONOMiCA," where a Japanese filename 飛び_右下.png failed to load on macOS.
Case 2: ZIP Filename Encoding Mismatch
Ren'Py's build system produces ZIP and tar.bz2 distribution files. The ZIP format has no standardized filename encoding.
Python 3's zipfile module sets the UTF-8 flag (bit 11) when writing, but older extraction tools and some Windows Explorer versions ignore this flag. The result: garbled filenames and a game that won't start.
Case 3: Web and Android Builds Are Untested
Ren'Py supports web browser builds (Emscripten/WebAssembly) and Android APK builds. However, there is no official confirmation that non-ASCII filenames work correctly on these platforms. Web builds have additional concerns around HTTP URL encoding interactions.
The Safe Alternative: ASCII Filenames + Aliases
Keep filenames in ASCII and use define aliases for readability in your scripts.
Audio Files
# Files in audio/ use ASCII names
# audio/battle_bgm.ogg
# audio/village_theme.ogg
# audio/rain_ambient.ogg
define audio.battle_bgm = "audio/battle_bgm.ogg"
define audio.village_theme = "audio/village_theme.ogg"
define audio.rain_ambient = "audio/rain_ambient.ogg"
label start:
play music battle_bgm
play sound rain_ambient
Creating aliases in the audio namespace with define means you never need to write file paths in play music statements. The variable name tells you what the audio is, so readability isn't a problem.
Image Files
Ren'Py's automatic image detection maps space-separated filenames to image names (see the image display docs).
images/
├── bg forest.png → scene bg forest
├── bg castle.png → scene bg castle
├── eileen happy.png → show eileen happy
└── eileen sad.png → show eileen sad
For manual definitions, stick to ASCII as well.
image bg forest = "images/bg_forest.png"
image bg castle = "images/bg_castle.png"
Naming Conventions
Establishing project-wide rules keeps things manageable as your file count grows.
# Audio
audio/{type}_{description}.ogg
audio/bgm_battle.ogg
audio/sfx_sword_slash.ogg
audio/amb_rain.ogg
# Backgrounds
images/bg {location}.png
images/bg forest.png
images/bg castle.png
# Characters
images/{name} {expression}.png
images/eileen happy.png
images/eileen angry.png
FAQ
Can I use Chinese, Korean, or accented Latin characters in filenames?
Yes, the same rules apply to all non-ASCII characters — they work in development but carry the same distribution risks. macOS normalization affects accented Latin characters (é, ñ, ü) just as much as CJK characters.
Do non-ASCII filenames work in Ren'Py 7.x?
Only partially. Ren'Py 7.x runs on Python 2, where strings are byte sequences by default. A 2014 fix resolved UnicodeEncodeError crashes for audio files, but Python 2's limited Unicode support makes non-ASCII filenames even riskier than in 8.x.
Will Ren'Py officially support Unicode filenames?
There's no indication of this. PyTom has consistently recommended ASCII filenames on the Lemma Soft Forums, and the official documentation makes no mention of Unicode filename support. Since it would require solving cross-platform normalization issues, official support seems unlikely.
Do non-ASCII characters in directory names cause the same problems?
Yes. Directory names go through the same filesystem operations as file names. A path like images/キャラクター/eileen happy.png has both the directory name and file name subject to normalization and encoding issues during distribution.
Can I use non-ASCII characters in Ren'Py label names or variable names?
Python 3 allows Unicode identifiers, so label 戦闘シーン: technically works. However, Ren'Py's script parser may not handle all Unicode identifiers consistently, and it makes collaboration with non-Japanese speakers difficult. Stick to ASCII for code identifiers.
How do I rename existing non-ASCII files to ASCII?
Rename the files in your OS file manager or with a batch rename tool, then update all references in your .rpy scripts. Search for the old filename string across your project. Adding define aliases after renaming makes future reference changes easier — you only need to update one line.
Does the macOS normalization issue affect APFS or only HFS+?
Both, though differently. HFS+ forcibly converts filenames to NFD on disk. APFS preserves the original byte sequence but uses normalization-insensitive comparisons for lookups. The practical result is similar: a filename written in NFC may not match a lookup expecting exact byte equality.
Wrapping Up
- Does it work? — Non-ASCII filenames work in Ren'Py 8.5.2 on most systems
- Why? — Python 3's native Unicode string handling. Not an official Ren'Py feature
- Risks — macOS normalization, ZIP encoding mismatches, untested Web/Android builds. Distribution can break silently
- Recommendation — ASCII filenames +
definealiases are safe and practical
For Ren'Py basics, see the getting started guide. For audio setup details, see the audio guide.
Official resources:
- Ren'Py Documentation — full reference for all features
- Displaying Images — image auto-detection and naming
- Audio — audio playback reference
- Python 3 Unicode HOWTO — deep dive into Python's string model
- Apple APFS Documentation — APFS normalization behavior
- r/RenPy — community for questions and discussion
Related articles: