Registry / serialization / vdf
library3.4pypypi✓ verified 86d ago

The `vdf` library is a pure Python module for serialization and deserialization of Valve's KeyValue (VDF) text and binary formats. It provides an interface similar to Python's built-in `json` module. The current version is 3.4, and it is actively maintained with an irregular release cadence, supporting KV1 format while KV2 and KV3 are not supported.

pip install vdf
INSTALL
IMPORT
SIG · VDF
V
vdf
serializationpythonv3.4
Install
1.5s avg
Import
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

vdf
import vdf
VDFDict
from vdf import VDFDict
import vdf.VDFDict
`VDFDict` is a class within the `vdf` module, commonly imported directly for clarity when used as a custom mapper.

This quickstart demonstrates how to parse and dump VDF data, including handling text and binary formats. It highlights the use of `vdf.VDFDict` for correctly managing duplicate keys and preserving order, which are common challenges with the VDF format.

import vdf from collections import OrderedDict vdf_text = '"Config" { "Key1" "Value1" "Key2" "Value2" "Key1" "AnotherValue" }' # Deserialize VDF text to a Python dictionary (loses duplicate keys prior to Python 3.7) data_dict = vdf.loads(vdf_text) print(f"Standard dict (may lose duplicates): {data_dict}") # Deserialize VDF text preserving order and handling duplicates with VDFDict data_vdfdict = vdf.loads(vdf_text, mapper=vdf.VDFDict) print(f"VDFDict (preserves order and duplicates): {data_vdfdict}") print(f"Accessing a duplicated key in VDFDict: {data_vdfdict['Config']['Key1']}") # Returns a list # Serialize a Python dictionary to VDF text output_dict = {'Game': {'Name': 'MyGame', 'Version': '1.0'}} vdf_output = vdf.dumps(output_dict, pretty=True) print(f"\nSerialized VDF:\n{vdf_output}") # Example of binary VDF (requires bytes input/output) # For demonstration, we'll simulate binary data. binary_vdf_bytes = b'\x00Config\x00\x00Key1\x00Value1\x00\x00Key2\x00Value2\x00\x08' binary_data = vdf.binary_loads(binary_vdf_bytes) print(f"\nDeserialized binary VDF: {binary_data}") # Example of VBKV (ValueBinaryKeyValue) with header and CRC checking # This often requires specific bytes patterns for actual Valve files. # For a real scenario, vbkv_bytes would come from a file. # Here, we'll just demonstrate the call. # try: # vbkv_data = vdf.vbkv_loads(b'some_vbkv_bytes_with_header_and_crc') # print(f"Deserialized VBKV: {vbkv_data}") # except Exception as e: # print(f"VBKV deserialization error (expected if bytes are not valid): {e}")
Debug
Known issues
gotchaThe VDF format allows duplicate keys within an object, but standard Python `dict`s do not (prior to Python 3.7 where insertion order is preserved, and later versions that handle duplicates differently). When deserializing VDF with duplicate keys, `vdf.loads()` or `vdf.load()` will, by default, overwrite earlier values for the same key.
fix
Use `vdf.loads(vdf_string, mapper=vdf.VDFDict)` or `vdf.loads(vdf_string, mapper=collections.OrderedDict)` to preserve all duplicate keys as a list of values, or to maintain insertion order, respectively. `vdf.VDFDict` is specifically designed to handle VDF's duplicate key behavior.
affects: <3.0
gotchaPython `dict`s in versions prior to 3.6 do not guarantee insertion order. If key order is crucial for your application when working with older Python environments, direct deserialization to a `dict` might lead to unexpected results.
fix
Always use `collections.OrderedDict` or `vdf.VDFDict` as the `mapper` when loading VDF data if key order is important, especially on Python versions older than 3.6. For example: `vdf.loads(vdf_text, mapper=collections.OrderedDict)`.
affects: <3.6
gotchaComments present in a VDF file are not preserved during the deserialization process. If you parse a VDF file that contains comments and then serialize it back, the comments will be lost.
fix
This is a fundamental behavior of the library; if comment preservation is critical, `vdf` might not be the suitable tool, or comments would need to be handled by a separate parsing layer before passing data to `vdf`.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'vdf'
The `vdf` package is either not installed in the active Python environment, or there's a conflict with multiple Python installations (e.g., system Python vs. `pyenv`/`conda`) where the package is installed for a different interpreter. This can also happen if a wrapper script (like `protontricks`) expects `vdf` in a specific Python version's `site-packages` that doesn't match the installed version.
fix
Ensure `vdf` is installed for your active Python interpreter using `pip install vdf`. If using virtual environments, activate the correct environment first. If using tools like `protontricks`, verify that the Python environment it targets has `vdf` installed, potentially by forcing installation for a specific Python version or ensuring path consistency.
TypeError: 'VDFDict' object is not subscriptable
This error can occur if you're trying to access a nested key directly on the top-level `VDFDict` object that doesn't exist at that level, or if you're attempting to treat a single value as a dictionary/list. It might also happen if a key that you expect to be a sub-dictionary is actually a single value due to parsing.
fix
Inspect the structure of your VDF data after deserialization. Remember that `VDFDict` works like `dict`, and nested values are accessed sequentially (e.g., `data_vdfdict['Config']['Key1']`). If duplicate keys exist, `VDFDict` stores them as a list of values, so you might need to iterate or access by index (e.g., `data_vdfdict['Config']['Key1'][0]`) if you're expecting a single string.
Upgrade
Version history
3.4latest on PyPI · released May 22, 2021
Audit
Dependencies

No dependency data recorded yet.

Agent activity
12 hits · last 30 days
node
10
Amazon
1
OpenAI (training)
1
Resources
vdf — pip install vdf · libregistry