Skip to main content

ValveMDL

License PyPI pyversions Platform PyPI version CI

A python library to read and write .mdl files, the model format of the Source engine, along with their .vvd and .vtx companions.

ValveMDL is about serialization and nothing else. It will read a model apart and put it back together; it will not transform meshes, render anything, or convert to other formats.

ValveMDL reads and writes all three files. Across a stock Team Fortress 2 install -- 9,858 models spanning format versions 44 to 48 -- a model read apart and written back is byte-for-byte identical to what studiomdl produced, with a single exception caused by orphaned data in one shipped file. See the documentation for the structure by structure detail.

Installation

pip install valvemdl

Usage

from valvemdl import Mdl

mdl = Mdl('models/props_farm/ambulance.mdl')

mdl.version         # 48
mdl.name            # 'ambulance.mdl'
mdl.header.numbones # 3

A model is really a set of files. An mdl contains no vertices and no triangles; those live in the .vvd and .vtx next to it, tied together by a checksum. Opening an mdl notices which of them are present but does not read them until you ask:

mdl.sidecar_paths   # {'.vvd': '...', '.dx90.vtx': '...', ...}
mdl.vvd             # parsed now, cached after
mdl.get_vtx('.sw.vtx')

On versions

Team Fortress 2 ships mdl versions 44, 45, 46, 47 and 48 -- five variants of the same format, in the same game. Version 48 accounts for about 91% of them. studiohdr_t is unchanged across that whole range.

ValveMDL is evidence driven: a structure is supported once it has been read out of real files and cross-checked against the Source SDK, and not before. Gaps are left as gaps rather than guessed at.

Contributing

Issues and pull requests are welcome. Be pythonic, document and test your code. That's all.

One extra rule applies here, because ValveMDL is as much a format reference as it is a library: do not guess. Every field, flag and version rule should trace back either to the Source SDK or to bytes observed in real model files. If something is unknown, say that it is unknown.

License

GPLv3

Metadata

Release files for valvemdl 0.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for valvemdl 0.0.2
File Size Uploaded Provenance Actions
valvemdl-0.0.2.tar.gz 66.2 kB With provenance Details for valvemdl-0.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for valvemdl 0.0.2
File Interpreter ABI Platform Actions
valvemdl-0.0.2-py3-none-any.whl Python 3 none any Details for valvemdl-0.0.2-py3-none-any.whl

Total release size: 140.6 kB

Release files / valvemdl-0.0.2.tar.gz

Download URL valvemdl-0.0.2.tar.gz
Size 66.2 kB
Tags Source
SHA-256 checksum
How to use checksums
75554152af8628c9c498d2465bf68f3637cd60c7e2999bd65d538818257f4047
BLAKE2b-256 checksum
How to use checksums
526068702b9d033315aed6bb04ddaa7e664fa1ebb4774dafcd762c67e2110151
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Release files / valvemdl-0.0.2-py3-none-any.whl

Download URL valvemdl-0.0.2-py3-none-any.whl
Size 74.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
021478d1e949c4cccead0ffa3bda57d63e50787ee1edb284f1ec8fe63c4fcf4f
BLAKE2b-256 checksum
How to use checksums
d335b0b20788c9278fe005bc6ea5dff02a308b2c72400bf1d041e3b8a28d17e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

Security for valvemdl 0.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for valvemdl-0.0.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page