{"id":3524,"library":"jsonnet","title":"Jsonnet Python Bindings","description":"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.","status":"active","version":"0.22.0","language":"en","source_language":"en","source_url":"https://github.com/google/jsonnet","tags":["configuration","templating","json","data-generation","compiler"],"install":[{"cmd":"pip install jsonnet","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The Python module for Jsonnet is imported as '_jsonnet', not 'jsonnet'.","wrong":"import jsonnet","symbol":"_jsonnet","correct":"import _jsonnet"}],"quickstart":{"code":"import _jsonnet\nimport json\n\n# Example Jsonnet snippet\njsonnet_snippet = '''\nlocal person(name='Alice') = {\n  name: name,\n  welcome: 'Hello ' + name + '!'\n};\n{\n  person1: person(),\n  person2: person('Bob'),\n  env_greeting: 'Hello from env ' + std.extVar('GREET_TARGET'),\n}\n'''\n\n# Evaluate a Jsonnet snippet\n# Note: For security, never pass untrusted input to ext_vars without proper sanitization/validation.\noutput_json_string = _jsonnet.evaluate_snippet(\n    'example.jsonnet', # Filename used in error messages\n    jsonnet_snippet,\n    ext_vars={'GREET_TARGET': 'World'}\n)\n\n# Parse the resulting JSON string into a Python object\noutput_data = json.loads(output_json_string)\n\nprint(json.dumps(output_data, indent=2))","lang":"python","description":"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."},"warnings":[{"fix":"Ensure bitwise operation arguments are within the safe-integer range. Review usage of `std.objectRemoveKey` if upgrading from pre-0.22.0 versions.","message":"Between 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.","severity":"breaking","affected_versions":">=0.22.0"},{"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.","message":"Pre-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.","severity":"breaking","affected_versions":">=0.22.0"},{"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.","message":"The `_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.","severity":"gotcha","affected_versions":"All versions"},{"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'])`.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Jsonnet 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}