MTL File Documentation

---

Technical details

Feature	Value
Full name	Material Template Library (Wavefront)
File extension	.mtl
MIME type	model/mtl
Format type	Plain ASCII text; material sidecar to OBJ geometry
Developer	Wavefront Technologies (now part of Autodesk)
Introduced	Late 1980s, alongside the Wavefront OBJ format
Open standard	Yes — open, widely implemented, de facto interchange
Shading model	Classic Phong (ambient / diffuse / specular), pre-PBR
Editable with text editor	Yes
Text marker	newmtl <name> block; files often open with a # comment
Linked from OBJ	Via an mtllib line; materials selected with usemtl
Colour keywords	Ka ambient, Kd diffuse, Ks specular (RGB floats 0–1)
Shininess	Ns specular exponent (0–1000)
Transparency	d (dissolve, 1 = opaque) or Tr (= 1 − d)
Optical density	Ni index of refraction (1.0 = no bending)
Illumination model	illum 0–10
Texture maps	map_Kd, map_Ks, map_Bump, map_d (relative paths)
Related extensions	.obj, .png, .jpg, .fbx, .dae
Specification	paulbourke.net/dataformats/mtl/

What is an MTL file?

MTL stands for Material Template Library, the material-definition half of the Wavefront OBJ format. Wavefront Technologies created both in the late 1980s for its Advanced Visualizer software; the company later merged into what is now Autodesk, but the pairing stuck and became a near-universal 3D interchange format. An OBJ file stores only geometry — vertex positions, texture coordinates, normals and faces — and says nothing about how a surface should look. All of that (colour, shininess, transparency, which image to paint on) lives in the .mtl. Its MIME type is model/mtl.

The two files are joined by name. Near the top of the OBJ is a line like mtllib chair.mtl, and before each group of faces the OBJ writes usemtl wood to select a material by name. The MTL then defines newmtl wood with its parameters. This is why you never open an .mtl directly: on its own it describes surfaces for shapes that are not there. You open the .obj, and the loader follows the mtllib line to the material file beside it. Everything below is the actual grammar of that file.

The newmtl block and how OBJ binds to it

An MTL file is a flat list of material blocks. Each begins with newmtl and a name, and everything until the next newmtl (or end of file) belongs to that material. The name is the linkage: it is the exact string the OBJ passes to usemtl.

# Blender MTL File: 'chair.blend'
newmtl wood
Ka 0.20 0.12 0.06      # ambient reflectivity (RGB, 0-1)
Kd 0.55 0.32 0.14      # diffuse (base) colour
Ks 0.30 0.30 0.30      # specular colour
Ns 96.0                # specular exponent (shininess)
Ni 1.45                # optical density / index of refraction
d  1.0                 # dissolve: 1.0 = fully opaque
illum 2                # illumination model
map_Kd textures/oak.png

Lines are whitespace-separated and case-sensitive in their keywords. A # begins a comment to end of line. Numeric colours are three floats in the 0–1 range, not 0–255. Blank lines and unknown keywords are skipped by most loaders, which is how vendor-specific extensions (the PBR Pr/Pm/Ps roughness-metallic keywords some exporters add) coexist with readers that ignore them.

Ka, Kd, Ks and Ns: the Phong reflectivity terms

MTL encodes a classic Phong reflection model, which splits a surface’s response to light into three colour terms plus a sharpness control. Understanding what each does explains almost every material you will see.

Keyword	Meaning
Ka r g b	Ambient colour: how the surface looks under uniform, directionless light
Kd r g b	Diffuse colour: the main perceived surface colour under direct light
Ks r g b	Specular colour: the tint of the shiny highlight
Ns value	Specular exponent, 0–1000: low = broad dull highlight, high = tight glossy dot
Ke r g b	Emissive colour: light the surface appears to give off (a common extension)

Of the three colours, Kd is the one that matters most: it is what people read as “the colour of the object”. Ks combined with a high Ns gives a small bright highlight typical of plastic or polished metal; a low Ns spreads that highlight into a soft sheen. Ka is often set equal to Kd or to a dark grey, and many modern renderers largely ignore it. Instead of a flat colour, any of these can be replaced by a texture map, described below.

Transparency, Ni, and the illum models

Transparency has two spellings in MTL, which is a frequent source of confusion. d is the dissolve: d 1.0 is fully opaque and d 0.0 is invisible. Tr is the inverse, transparency, so Tr 0.0 equals d 1.0. A file may use either, and a robust loader treats Tr as 1 − d. The Ni keyword is the optical density (index of refraction): 1.0 bends nothing, glass is around 1.5, and it only affects refractive illumination models.

The illum keyword selects one of eleven fixed illumination models, numbered 0 to 10, that tell the renderer which terms to actually apply:

illum	Behaviour
0	Constant diffuse colour, no lighting (Kd only)
1	Diffuse + ambient, no specular highlight
2	Diffuse + specular highlight (the most common value)
3	Adds ray-traced reflection
4–7	Glass / refraction / Fresnel combinations for ray tracing
8–9	Reflection and glass without ray tracing
10	Casts shadows onto invisible surfaces

In practice most exported materials use illum 2, because real-time viewers and game engines only honour the diffuse-plus-specular case; the ray-traced models (3 and up) matter to offline renderers.

Texture maps: map_Kd, map_Bump and relative paths

Any colour term can point to an image instead of a constant. map_Kd oak.png paints the diffuse colour from a texture, map_Ks maps the specular colour, map_d supplies a per-pixel opacity mask, and map_Bump (or bump) supplies a bump or normal map that perturbs the surface without adding geometry. Map lines can carry options before the filename, for example map_Bump -bm 0.5 rock_n.png to scale the bump strength, or -s to scale UVs.

The critical practical point is that these paths are almost always relative to the MTL file. When a 3D program exports a textured OBJ it writes map_Kd oak.png or map_Kd textures/oak.png, expecting the image to sit right there. Move the .mtl without its images, or send only the .obj, and the loader cannot resolve the maps. That is the single most common failure: the model appears as a flat grey shape because the geometry loaded but every map_* path pointed at a file that is not next to the MTL. A textured OBJ is really a three-part bundle — .obj + .mtl + the image files — and it must travel as a folder.

Why MTL is never converted to OBJ

People sometimes look for a way to “convert MTL to OBJ”, but the two are not alternative formats; they are two halves of one model. The OBJ holds the shape, the MTL holds the surface, and the OBJ already references the MTL. There is nothing to convert between them. If a model arrives as an .mtl alone, it is incomplete: the geometry it describes materials for is missing. To carry MTL materials into a modern pipeline you import the .obj (which pulls in the MTL and textures) into a tool like Blender and export something like FBX or glTF; the classic Kd/Ks/map_Kd values become that format’s materials. You export the whole model, never the .mtl in isolation. It is also worth knowing that MTL predates physically based rendering: its Phong terms do not map cleanly onto the roughness/metalness workflow of glTF, so a conversion approximates rather than reproduces the look.

Frequently asked questions

My OBJ model loaded grey with no textures. Why?

The material file or the images it names are missing or in the wrong place. The OBJ’s geometry loaded fine, but the loader could not find the .mtl named in mtllib, or the map_Kd paths inside the MTL pointed at image files that are not beside it. Keep the .obj, the .mtl and every texture image in the same folder, and re-open the .obj (not the .mtl).

Can I edit an MTL by hand?

Yes. It is plain ASCII, so you can change a colour with Kd r g b, adjust shininess with Ns, flip opacity with d, or repoint a texture by editing the map_Kd filename in any text editor. Save it next to the OBJ and re-import. For visual edits, change the material in a 3D app and re-export.

References

• Paul Bourke — MTL material format reference
• Wikipedia — Wavefront .obj file (MTL section)
• Blender Manual — Wavefront OBJ import/export

Feedback

Was this page helpful?

Yes No

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.