What is an .obj file? Why it arrives without textures, and how to open it on a Mac

Readable text, line by line

A whole octahedron in OBJ looks like this:

o octahedron
v 10 0 0
v -10 0 0
v 0 10 0
v 0 -10 0
v 0 0 10
v 0 0 -10
f 5 1 3
f 5 3 2
f 5 2 4
f 5 4 1
f 6 3 1
f 6 2 3
f 6 4 2
f 6 1 4

A v line is a vertex, an f line a face made of vertex numbers. Counting starts at one, and a negative number counts backwards from the current line. Unlike STL, faces here share vertices, so the file doesn't repeat the same point. A face doesn't have to be a triangle, either: quads and general polygons are fine.

An export from Blender adds normals (vn), texture coordinates (vt), smoothing groups (s) and, above all, a reference to the materials file:

# Blender 5.1.0
mtllib cylinder.mtl
o cylinder
v 17.677670 0.000000 17.677670
vn -0.0000 -1.0000 -0.0000
s 0
f 1//1 2//1 3//1

1//1 means vertex 1 with normal 1, and no texture coordinate.

The .mtl file and textures: what has to travel with an OBJ

Colours and materials aren't in the OBJ but in a file the OBJ names on its mtllib line. In the .mtl, each material sits under newmtl, its colour under Kd and its texture under map_Kd as a path to an image. So a model is often three kinds of files at once:

• the .obj with the geometry,
• the .mtl, with exactly the name on the mtllib line,
• the texture images at the paths the .mtl gives, often in a subfolder.

I tried it with Apple's Model I/O framework. A triangle with Kd 1 0 0 in its .mtl loads red, and a texture from a subfolder loads too. When the .mtl isn't next to the .obj, the framework reports "Unable to find mtl file" and the model is white.

How easily the link breaks shows in Preview3D's own test set. The file 07-mesh.obj was renamed and its .mtl is called 07-mesh.mtl, but the OBJ still says mtllib cylinder.mtl. Renaming one file was enough. An absolute texture path in the .mtl, such as C:\Users\…, does the same on another computer.

So send an OBJ as a whole folder or a ZIP. If you need a model with its textures in one file, save it as GLB.

No units, no hierarchy

OBJ has no units. Blender exported a cylinder 54 mm across as 54 × 25 × 54 (with the Y axis up); in glTF the same cylinder would be 0.054. What the numbers mean, a program can only guess on import.

OBJ also has no object hierarchy, animation, cameras or lights. Per-vertex colours (v x y z r g b) aren't part of the specification. Scanners use them most, and only some programs read them – according to the Library of Congress, MeshLab, three.js and Preview on the Mac, for example.

Where OBJ came from

OBJ was made for Wavefront Technologies' Advanced Visualizer. Nobody knows the exact year; the Library of Congress says "around 1990". The description survives as an appendix to a manual from about 1992, the .mtl description from 1995. Wavefront merged with Alias in 1995, and Autodesk bought Alias in 2006. The format is openly described, but nobody maintains it.

The specification also describes NURBS and Bézier curves and surfaces that almost no program reads, and mentions a binary .mod variant that was never documented.

How to open OBJ on a Mac, iPad and iPhone

macOS knows OBJ by itself. According to the Library of Congress, Preview has opened it since OS X 10.11, and on macOS 27 (checked on 27.0.1) Quick Look and Finder thumbnails show it too. Because OBJ is text, it may open in TextEdit if the default app has changed. Then choose Get Info → Open With in the Finder, pick Preview and click Change All.

Other options:

• [Blender](https://www.blender.org/) and [MeshLab](https://www.meshlab.net/) are free and open OBJ with its materials.
• Preview3D, my app, opens OBJ on Mac, iPad, iPhone and Apple Vision Pro.

Preview3D reads OBJ through Model I/O. When a file has no normals, it computes them, so the model doesn't come out flat or black. Model info shows the dimensions in the file's own units and the triangle count, with a mesh check. There are three views with crease lines. On iPad and iPhone it stands the model on your desk in AR, fitted to the desk, because OBJ has no unit.

Converting OBJ to STL

On a Mac, Preview3D converts from File → Export model as… (⌥⌘E) to STL or PLY, without uploading anything. STL knows only triangles, so quads and polygons are split on the way. The numbers stay the same, so check the size in the slicer after converting. And STL carries no materials or textures.

Common questions

Why did my OBJ open without textures?

Its .mtl or images are missing, or their names and paths don't match. Keep the .obj, the .mtl and the textures in one folder, and check that mtllib in the OBJ names the right .mtl.

What is an .mtl file?

A text file of materials for an OBJ: colours, shininess and texture paths. The OBJ refers to it by name.

Does OBJ have units?

No. The coordinates are just numbers, and a program guesses on import whether they're millimetres or metres.

Is STL or OBJ better for 3D printing?

For a single-colour part, STL is enough. OBJ is useful when you need materials and textures. For colour printing, 3MF is the format made for it.

Does a Mac open OBJ without another app?

Yes, Preview and Quick Look handle it.

Why does my OBJ open in TextEdit?

OBJ is text, and its default app may have changed. In the Finder, choose Get Info → Open With, pick Preview or another 3D viewer, and click Change All.

Related pages

• The .stl file – the printing format OBJ is most often converted to
• The .gltf and .glb files – a model with its textures in one file
• The .fbx file – whole scenes, animation included

Sources

• Library of Congress: OBJ – history, vertex colours, Preview support
• Paul Bourke: the OBJ format and MTL
• IANA: model/obj
• Apple: Model I/O)
• Blender Artists: .mtl files won't load
• three.js: textures not loading with OBJLoader and MTLLoader

Do you have an OBJ that arrived on your Mac without textures, even though the .mtl was right next to it? Write to me at apps@xfanta.com with the program it came from.