jsonnet

library0.22.0pypypi✓ verified 23d ago

Jsonnet is a data templating language that helps you generate configuration data. The `jsonnet` Python library provides official Python bindings for the original C++ implementation, allowing evaluation of Jsonnet code from Python. The current version is 0.22.0, released on March 24, 2026. Releases are made periodically, typically driven by updates to the core Jsonnet language and its C++ implementation.

serialization

pip install jsonnet

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSONNET

jsonnet

serializationpythonv0.22.0

Install

1.7s avg

Import

—

Disk

41MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.22.0 · 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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 41.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.000s · 45MB

41MB installed

● package 41MB

Code

Verified usage

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

_jsonnet

✓ import _jsonnet

✗ import jsonnet

The Python module for Jsonnet is imported as '_jsonnet', not 'jsonnet'.

This quickstart demonstrates how to evaluate a Jsonnet snippet using `_jsonnet.evaluate_snippet` and access external variables. The output is a JSON string, which is then parsed into a Python dictionary.

import _jsonnet import json # Example Jsonnet snippet jsonnet_snippet = ''' local person(name='Alice') = { name: name, welcome: 'Hello ' + name + '!' }; { person1: person(), person2: person('Bob'), env_greeting: 'Hello from env ' + std.extVar('GREET_TARGET'), } ''' # Evaluate a Jsonnet snippet # Note: For security, never pass untrusted input to ext_vars without proper sanitization/validation. output_json_string = _jsonnet.evaluate_snippet( 'example.jsonnet', # Filename used in error messages jsonnet_snippet, ext_vars={'GREET_TARGET': 'World'} ) # Parse the resulting JSON string into a Python object output_data = json.loads(output_json_string) print(json.dumps(output_data, indent=2))

jsonnet --version

Debug

Known issues

breakingBetween versions 0.21.0 and 0.22.0, bitwise operation arguments are now limited to the 'safe-integer' range (IEEE754 double-precision floating-point integers). Code relying on bitwise operations outside this range will now error. The internal `std.objectRemoveKey` function was also re-implemented to fix several bugs and unexpected behaviors, which might subtly change outcomes for complex object manipulations.

fix

Ensure bitwise operation arguments are within the safe-integer range. Review usage of `std.objectRemoveKey` if upgrading from pre-0.22.0 versions.

affects: >=0.22.0

breakingPre-built Python binary wheels (used during `pip install`) now use the Python Limited API (ABI3 compatible) since version 0.22.0. This improves compatibility with newer Python versions, but might require recompilation or specific build environments if you are building from source against an older or non-standard Python setup.

fix

For most users installing via `pip`, this should be seamless. If you encounter build issues when installing from source, ensure your Python environment and compiler toolchain are up-to-date and compatible with ABI3.

affects: >=0.22.0

gotchaThe `_jsonnet` library, being a binding to the C++ implementation, is not hardened for untrusted inputs and poses significant security risks (data exfiltration, denial of service) if used to evaluate arbitrary, untrusted Jsonnet code. The `import`, `importstr`, and `importbin` constructs can read any file accessible to the interpreter process.

fix

NEVER evaluate untrusted Jsonnet code without robust sandboxing (e.g., gVisor, Firecracker VM) and/or implementing a custom `import_callback` to restrict file access. For API servers, `exec` the Jsonnet CLI in a `ulimit` child process to bound CPU/RAM.

affects: All versions

gotchaWhen using `_jsonnet.evaluate_snippet()` for Jsonnet code that contains `import` statements, the interpreter needs to know where to search for imported files. Without specifying `jpathdir` or providing a custom `import_callback`, these imports will fail.

fix

Always provide the `jpathdir` argument (a string or list of directory paths) to `evaluate_snippet` if your Jsonnet code uses imports, or implement a custom `import_callback` function for more advanced import logic. Example: `_jsonnet.evaluate_snippet('name', snippet_code, jpathdir=['./my_jsonnet_libs'])`.

affects: All versions

gotchaJsonnet is a lazy evaluation language. This means expressions are only evaluated when their value is actually needed. This can lead to unexpected behavior regarding errors or performance, as code that appears before an error-inducing line might not be evaluated, or computationally intensive parts might only run when accessed.

fix

Be mindful of Jsonnet's lazy evaluation model, especially when debugging errors or optimizing performance. Understand that variable initializers are not evaluated until the variable is used. Explicit assertions can help pinpoint evaluation issues.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'jsonnet'

The `jsonnet` Python package has not been installed in your current Python environment.

fix

pip install jsonnet

RuntimeError: STATIC ERROR: <filename>:<line>:<column>: Unknown variable: <variable_name>

This error occurs when the Jsonnet code being evaluated attempts to use a variable or external variable that has not been defined or passed into the evaluation context.

fix

Ensure that all variables referenced in the Jsonnet code are either defined within the Jsonnet file itself, or passed as `ext_vars`, `ext_codes`, `tla_vars`, or `tla_codes` arguments to `_jsonnet.evaluate_file` or `_jsonnet.evaluate_snippet` in Python. For example: `_jsonnet.evaluate_snippet('snippet.jsonnet', 'std.extVar("myVar")', ext_vars={'myVar': 'value'})`

RuntimeError: File not found

When using `_jsonnet.evaluate_file` or `_jsonnet.evaluate_snippet` with Jsonnet code that contains `import`, `importstr`, or `importbin` statements, the interpreter cannot find the specified file(s) in its search paths or the default import callback.

fix

Provide a `jpathdir` argument (a string or list of strings) to `_jsonnet.evaluate_file` or `_jsonnet.evaluate_snippet` to specify directories where imported files should be searched. Alternatively, implement a custom `import_callback` function to handle file resolution logic.

ImportError: dlopen(...) Symbol not found: _PyString_AsString

This usually indicates an incompatibility between the compiled C++ Jsonnet binding and the Python interpreter, often due to building with one Python version's headers and running with another, or issues with dynamic library linking on the operating system.

fix

Ensure your Python environment, build tools, and `jsonnet` installation are consistent. Try reinstalling `jsonnet` in a clean virtual environment or updating your system's development tools (e.g., Xcode on macOS, build-essential on Linux). If building from source, ensure the correct Python version's headers are used. This specific error has been noted in older Python 3.5 contexts.

jsonnet.JsonnetError: <filename/snippet>:<line>:<col> <error message>

There is a syntax error, a runtime error, or an unhandled exception within the Jsonnet code being evaluated by the Python binding.

fix

Examine the Jsonnet code snippet or file at the indicated line and column to correct the syntax or logic error.

Upgrade

Version history

0.22.0latest on PyPI · released Mar 24, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/google/jsonnet ↗

packagehttps://pypi.org/project/jsonnet/ ↗

homepagehttps://jsonnet.org ↗