Skip to content

Basic information & syntax

OptiGUI supports two syntaxes:


To prevent loading an OptiFine .properties file on OptiGUI, add optigui.ignore=true into it.

OptiGUI files support conditional loading.

OptiGUI syntax is only supported for OptiGUI files, and the OptiFine syntax is only supported for OptiFine files. Do not mix them.

This page describes the OptiGUI syntax. For the OptiFine syntax, visit the link above.

File naming rules

Each file in a resource pack must only contain characters a-z 0-9 _. All lowercase, no whitespace. Otherwise, the game will not recognize it.

Each file name must match the regular expression ^[a-z0-9_]+$

Textures must be PNG images with .png extension.

All text files must be encoded in UTF-8. Do not use an ASCII encoding.

File structure

OptiGUI uses INI files, kind of like OptiFine, but uses more features of it.

# Comments start with a hashtag
; or a semicolon

All selectors are case-sensitive: name is not the same as Name. The order of selectors within the file or within a group does not matter.


Groups start with [square bracketed] identifiers. Place the identifier of the container to replace the GUI.


Go to the Minecraft Wiki. Select a container (for example, a chest, horse, crafting table, etc.), scroll down to Data values/ID/Java Edition, and copy the text from the Identifier column. This identifier is used by the /give and /summon commands.

If multiple selectors are specified in a group, they all must match in order to apply the replacement texture. If incompatible selectors are specified (for example, llama.colors to [chest], it will never match).

# Selectors here apply to minecraft:chest
# If namespace is omitted, the default is minecraft

# Starts a new group
# Selectors here apply to minecraft:barrel

[horse minecraft:llama]
# Selectors here apply to both horses and llamas
# Namespaces and the lack of them can be mixed
# The default namespace is minecraft
white_spaces = are_trimmed
# Is the same as

[chest #2]
# [chest] is not allowed again
# Anything specified after a hashtag is ignored
# Useful when want to replace the GUI of the same container, but with different selectors

[#3 chest]
# Hashtags can be anywhere between the square brackets
# Remember, the group accepts a list of identifiers, a hashtag's scope lasts until the next whitespace
# Here, only #3 is ignored, but not chest



Always use forward slashes (/) to separate folders.

Regardless of operating system (Windows, Mac, *nix), do not use backslashes (\), or the game will not properly recognize the path.

OptiGUI paths can be specified in two ways: relative and absolute.

# Relative path (relative to the folder the INI file is in)

# You can use current and parent directory

# Absolute (namespace prefix)


Contrary to OptiFine, OptiGUI requires the file extension (.png here) to be specified. If it is not specified, OptiGUI will not find the texture!


Tildes (~) are not supported by OptiGUI. When loading OptiFine .properties, OptiGUI will expand them.


OptiGUI supports exact values, and case-sensitive and case-insensitive variants of wildcards and regexes. However, these are not prefixed with regex:, iregex:, pattern:, or ipattern:. The accepted type (wildcard, regex, ...) depends on the selector, and always noted explicitly.


Any backslashes must be doubled. Matching backslashes within a regular expression or wildcard must be quadrupled.

✅ Correct: name=regex:\\d+, name=regex:\\\\,\\/\\

❌ Wrong: name=regex:\d+, name=regex:\\ (for matching ), name=/\/\\ (missing a backslash)

Exact value

Letter to Herobrine matches Letter to Herobrine, and nothing else.


You may use the following characters to match other characters:

Character Regex equivalent Meaning
* .+ Matches 1 or more characters
? .* Matches 0 or more characters


Regular expressions "patterns" other strings can be matched against.

OptiGUI understands the Java syntax. Expression flags are not supported.

You can use the RegExr tool to create and test your regexes. When pasting into az OptiGUI INI file, make sure to duplicate all backslashes (\), as OptiGUI will unescape any escape sequences Java supports (like hexadecimals, line breaks, and unicode codepoints).


Numbers can be specified as a signed or unsigned integer.


number = 1


Inclusive ranges between numbers are defined with a - between the minimum and the maximum number. The right side is optional: if it is omitted, the upper bound will be positive infinity.


OptiGUI usually allows specifying ranges as lists


# 1, 2, 3
numbers = 1-3

# Multiple ranges
# 1 through 3, or 6, or 8, or 10 through 15
# 1, 2, 3, 6, 8, 10, 11, 12, 13, 14, 15
numbers = 1-3 6 8 10-15

# Greater than or equal to
# 100, or 200, or 5340, or 25902, etc.
numbers = 100-

# Negative number, not a range
# Only matches negative 100, not -4, -7, or -101
numbers = -100

# Negative numbers must be surrounded with parenthesis
numbers = (-1)-(-3)


There is no range to specify relation, you need to specify the lower bound: 0-100. -100 is a number, and will only match -100.


The range: prefix is not supported by OptiGUI and will be ignored when loading OptiFine .properties.


Booleans are case-insensitive.

Possible values: true, false. Everything else is ignored.


Lists can hold multiple elements separated with a whitespace. The element type is specified by the selector, it can be any type, like numbers or booleans. Strings are also supported, however, whitespaces within a string will start a new list element (and therefore, cannot be specified in strings inside lists).

If multiple elements are specified in a list, any of them can match in order to replace a texture.


Dates can be specified by the name, the first 3 characters of its name, or number of the month, and an optional day number or day range separated with a @ character:


# January
date = january
date = jan
date = 1
# These are all equivalent to:
date = jan@1-31

# October 1-5, 11-15, 21-25
date = oct@1-5 10@11-15 october@21-25
# The following is not valid:
invalid_date = october@1-5,11-15,21-25

# Christmas
christmas = dec@24-26

# Not Christmas
not_christmas = 1 2 3 4 5 6 7 8 9 spooktober 11 dec@1-23 dec@27-31

Supported month abbreviations

Month Abbreviations
January 1, jan, january
February 2, feb, february
March 3, mar, march
April 4, apr, april
May 5, may
June 6, jun, june
July 7, jul, july
August 8, aug, augustus
September 9, sep, september
October 10, oct, october, spooktober
November 11, nov, november
December 12, dec, december


Villager professions can be specified by an optional namespace and the profession name name, and an optional level or levl range separated with a @ character:


villager.professions = cleric minecraft:fisherman           # Cleric (any level) or fisherman (any level)
villager.professions = fletcher@1 minecraft:fletcher@3-4    # Fletcher (levels 1, 3, 4)