An open, clean-room reader, writer and specification for the SketchUp .skp
file format: releases 3 to 8 and 2013 to 2020 (the stream container) and
the 2026 container that SketchUp 2026 and 2027 save, read and written
through one library. Releases 2021 to 2025 are supported through the
2026 container; see the support matrix.
SketchUp's native format has no public specification and, until now, no
open-source reader; the only way to read a .skp has been Trimble's
proprietary SDK. Skpwright documents the two containers, reads any file
into one model, and writes that model back out as a file of any stream
release or of the 2026 container (see the support matrix):
- A format specification —
docs/SKP_FORMAT.mdplus the Kaitai Struct grammarksy/skp.ksy, detailed enough to build an independent parser. - A Rust SDK —
crates/skpwright, a pure-Rust library (its only dependency is a DEFLATE decoder) that reads meshes, materials, UVs, hierarchy, layers, scenes, attributes, and the document's settings (camera, rendering options, shadows, units, styles, watermarks, and text/dimension annotations), and writes a model as a file of a stream-container release or the 2026 container, or edits a file in place. - A CLI and a C ABI —
skpwright, which converts a file between the supported releases, summarises it and prints it as JSON (skpwright --help), andlibskpwrightwith a plain-C header for every other language. - An evidence corpus —
corpus/, the authored minimal pairs, per-release checkpoint sets and ground-truth exports behind every format claim, doubling as the test suite's oracle.
Everything derives from observing .skp files, SketchUp's own exports
of them (COLLADA, and model dumps scripted in its Ruby console), and
public knowledge of MFC CArchive serialization and the ZIP format.
No Trimble SDK, headers, or SDK-derived knowledge is used; SketchUp
is only ever operated, never read — see the clean-room policy in
CONTRIBUTING.md.
Every observed release is stored in one of two containers. Both begin with the
same two UTF-16 string records, which carry the version string
({3.x} … {20.x}, {26.x}, {27.x}).
The stream container holds releases 3 to 8 and 2013 to 2020
({3.x} to {20.x}): after the header comes one uncompressed MFC
CArchive object stream with a single shared object map, where classes
are defined lazily inline and object references index that map. The
layout in §2–§13 is written as release 2017 writes it; §14 derives every
other release from it as delta rules.
The 2026 container ({26.x} and {27.x}, as saved by SketchUp 2026 and 2027, and by
2021 to 2025) follows
the header strings with a ZIP archive. Its model.dat is a tree of
tagged records (u16 tag | u32 length | payload) holding the entities,
their persistent ids, transforms, and every document setting; materials
are XML files next to their texture images.
Both store the same model: a half-edge kernel (CVertex / CEdge /
CEdgeUse / CLoop / CFace) in f64 inches, components and groups
placing shared definitions through 13-value transforms, and textures
mapped through per-face projective matrices. The full account is in
docs/SKP_FORMAT.md: §2–§14 for the stream
container, §16 for the 2026 container.
git clone https://github.com/hew3d/skpwright
cd skpwright
cargo run -p skpwright-cli --release -- model corpus/2026/house-plus.skp
cargo run -p skpwright-cli --release -- mesh corpus/2026/box.skp # JSON out
cargo run -p skpwright-cli --release -- model corpus/2017/house.skp # stream container, release 2017
cargo run -p skpwright-cli --release -- model corpus/8/box.skp # stream container, release 8
cargo run -p skpwright-cli --release -- convert --to 2013 corpus/2026/box.skp out.skpAs a library:
let model = skpwright::Model::read("model.skp")?; // any observed release
for run in &model.geometry {
// a 1 m box: 8 vertices / 12 edges / 6 faces
println!("{:?}", run.topology);
}
for node in model.scene() {
// composed world transforms, inherited materials
}From C (or anything that speaks JSON):
skpwright_model *m = skpwright_open("model.skp");
puts(skpwright_mesh_json(m)); /* meshes + composed scene */
skpwright_free(m);See docs/SDK.md for the full API tour.
The corpus is the oracle. Every decoded structure is validated three ways: by construction (files authored with typed exact dimensions, so the right bytes are knowable in advance), against COLLADA (SketchUp's own exports provide ground-truth coordinates, connectivity, colors, and UVs), and at scale (a 10.6 MB production model must match its export exactly — 41,725 world vertices, 26,918 face rings, and 7,649 textured faces' UVs do).
cargo test --workspace --release # the acceptance suite
./scripts/verify.sh # Kaitai grammar + reference-parser checksverify.sh needs a Python venv with kaitaistruct and an
npm install kaitai-struct-compiler js-yaml.
The stream container (releases 3 to 8 and 2013 to 2020) is read and written
through one grammar, and every one of its releases has files SketchUp
wrote. The 2026 container (a ZIP archive holding model.dat) has two
observed versions: {26.2.0} (revision 17, the web app)
and {27.0.267} (revision 18, SketchUp Pro 2027). SketchUp 2027's "save
as 2021" option writes the same {27.0.267} format, so desktop saves of
2021 to 2025 use the same container. The container is one format whose
model revision (meta/meta.dat, spec §16.27), not its version label, is
the gate: SketchUp 2027 opened every revision tried up to 18 under every
label tried. A hand-edited file of revision 19 or above was refused by
SketchUp 2027 desktop (the web app accepted it); no real file above 18
exists. The reader reads any revision (one above 18 as 18,
with a diagnostic; records are length-framed and unknown tags are
reported). The writer emits only revision 17 as {26.2.0} or revision 18 as
{27.0.267}, the lowest that holds the model unless asked for one.
Releases 2021 to 2025 are supported: files from them read like any
revision up to 18 (a 2021 file observed holds revision 8, a 2022 file
13). The writer's revision 17 is the lowest it emits; no application of
2021 to 2025 has opened a file of it.
Status words: native files in corpus (files a SketchUp release wrote are committed and read whole), written by Skpwright and accepted by SketchUp N (a file Skpwright wrote was opened and re-saved by SketchUp N with matching content), supported by the shared container.
| release | container | read evidence | write evidence |
|---|---|---|---|
| 3, 4, 5, 6, 7, 8 | stream (§14.4) | native files in corpus (10 per release, written by SketchUp Make 2017 saving to the release) | written by Skpwright and accepted by SketchUp Make 2017 |
| 2013 to 2016 | stream (§14.2) | native files in corpus (10 per release, written by SketchUp Make 2017) | written by Skpwright and accepted by SketchUp Make 2017 |
| 2017 | stream (§2-§13) | native files in corpus (92 authored pairs, third-party models) | written by Skpwright and accepted by SketchUp Make 2017 |
| 2018 | stream (§14.5) | native files in corpus (SketchUp 2027's save of each of the 92 2017 models read equivalent, 15 committed) | written by Skpwright (all 92 models) and accepted by SketchUp 2027 with matching content |
| 2019 | stream (§14.5) | as 2018 (16 committed) | as 2018 |
| 2020 | stream (§14.5) | as 2018 (20 committed) | as 2018 |
| 2021 to 2025 desktop | 2026 (§16) | supported through the shared container; the revision is the gate (§16.27); two real files observed outside the corpus ({21.0.0}, revision 8; {22.0.353}, revision 13), read whole |
revision 17 files are written; not opened in those apps, and below the revision 17 the tool writes, so whether they open there is untested |
2026 ({26.2.0}) |
2026 (§16) | native files in corpus (91, saved by the web app; no hatch, environment, CRS or procedure sections) | written by Skpwright and accepted by the SketchUp web app and by SketchUp 2027 with no integrity warning |
2027 ({27.0.267}) |
2026 (§16) | native files in corpus (88 one-change files, SketchUp Pro 2027; its saves of the 92 2017 models read equivalent) | written by Skpwright (every corpus file) and accepted by SketchUp 2027 with no integrity warning |
Notes: a file whose header strings are followed by a ZIP archive is read as
the 2026 container whatever its version string. Releases before 2017 were
checked against the full 92-file same-session save sets (outside the
repository, pinned by hash) as well as the committed checkpoint sets.
Writing to an earlier release drops what that release cannot hold and
reports each drop as a note. Any Model writes as a stream-container
release 3 to 2020 or as the 2026 container at revision 17 or 18; releases
2021 to 2025 have no label of their own and take revision 17. A file's
version string is {A.B.C}: A is the release, and B.C (the saving
build) varies within one without changing the layout of the stream
container (spec §2); the 2026 container's gate is the model revision.
- Reading at scale. Every 2017 corpus file but
section-plane-deactivated.skphas a 2026 twin; each twin reads equivalent to its original (geometry, hierarchy, materials, layers, UVs, scenes, guides, document settings), and the COLLADA-oracle tests run on both containers. The 2026 reader is the faster and lighter of the two (a 122 MB production model: 1.2 s and 384 MB as a 60 MB 2026 file, 2.2 s and 544 MB as the release 2017 original). The stream container's walk reads production-scale models well beyond the corpus (a 464 MB third-party house in 12 s and 2 GB; these are local models outside the repository, seeSKPWRIGHT_EXTERNAL_MODELSindocs/DEVELOPMENT.md) with no desync; a process that cannot hold the model gets a named out-of-memory error instead of aborting. - Damaged records. A damaged record is skipped and reported as a diagnostic; a record tag this reader does not know, at the top level or in an entity container, is reported rather than dropped.
- Writing 2026 files. A 2026 file round-trips byte for byte through
the lossless
Document(its DEFLATE streams re-encoded exactly), anyModel— read from either container or built by another program — writes as a 2026 file withModel::writethat SketchUp 2027 and the web app opened and re-saved with matching content and that reads back equivalent, and aDocumenttakes surgical edits (a colour, a transform, a coordinate) that change one record and nothing else (docs/WRITING.md). - Writing stream-container files. Every byte of a stream-container
file is read as records and written back identical through a store map
assigned anew, so any
Modelalso writes as a file of any release 3 to 2020 (Model::write_as,skpwright convert --to <release>) and reads back equivalent. Every written release up to 2017 was opened and re-saved by SketchUp Make 2017 without a dialog, with matching content, and the releases 2018 to 2020 by SketchUp 2027 (docs/DEVELOPMENT.md, SketchUp acceptance). Writing to an earlier release drops what that release cannot hold and reports each drop as a note. AStreamDocumenttakes in-place edits byte for byte. What a written file carries, what it leaves behind and what is unknown is inventoried indocs/WRITING.md. - Post-2017 features. What SketchUp 2027 adds to the 2026
container (hatch patterns, layer folders and line styles, physically
based materials, environments, ambient occlusion, a coordinate
reference system, snaps and Solid Tools results, and the newer page
settings) reads into
Model::featuresand writes back, pinned by the one-change files ofcorpus/2027and specified indocs/SKP_FORMAT.md§16.17 to §16.26. A stream-container file holds none of it, and writing one drops it with a note per kind.
Caveats. Every observed file of releases 3 to 6 and 2013 to 2016 was
written by SketchUp Make 2017 saving to that release; releases 7 and 8 have also been read from files SketchUp 7 and 8 themselves wrote, models outside the repository;
nothing written by SketchUp 3 to 6 themselves has been seen, so a few
layout details of those releases are marked candidate in the spec. Release
2017 has 92 authored minimal pairs, COLLADA oracles and production-scale
third-party models, and 2026 has a twin of every 2017 file but one plus a
production model; each other release has ten committed files (eleven
from 2018; the checkpoint set, corpus/README.md),
a mutation test showing those files detect every per-release rule that
reading them or writing them back consults (docs/DEVELOPMENT.md), and
the releases before 2017 also a pinned 92-file same-session save set
checked when SKPWRIGHT_YEARS_DIR is set. The files of 2018 to 2020 were
written by SketchUp 2027 saving to that release. Reading is the same code
path for all; the volume of evidence behind each release is not equal.
Releases 2021 to 2025 are supported: a file whose header strings are
followed by a ZIP archive is read as a 2026 file at the revision its
meta/meta.dat declares.
docs/ SKP_FORMAT.md (the spec) · SDK.md (using the SDK) · DEVELOPMENT.md
ksy/ skp.ksy — Kaitai Struct grammar (header + record catalogue)
crates/ skpwright (core library) · skpwright-cli · skpwright-capi (C ABI)
corpus/ the evidence base: authored 2017 minimal pairs and their 2026
twins, a checkpoint set for each other release (3 to 8 and
2013–2016, 2018–2020), one-change files saved by SketchUp
2027, ground-truth exports in model/, a full-scale
third-party benchmark in both containers (see corpus/README.md)
tools/ Python analysis instruments and the frozen reference parser
scripts/ verify.sh
GPL-3.0-only — see LICENSE. Alternative commercial licensing
may be offered in the future; contributions are accepted under the terms
in CONTRIBUTING.md, which keep that possible.
SketchUp is a trademark of Trimble Inc. This project is independent of
and unaffiliated with Trimble; it interoperates with the .skp format
based on clean-room analysis of files. Texture images embedded in the
corpus .skp files are third-party content outside the GPL grant — see
corpus/README.md.