{"id":9589,"library":"clvm-tools","title":"CLVM Tools","description":"clvm-tools is the official compiler for CLVM (Chia Lisp Virtual Machine) programs. It provides utilities for assembling CLVM code from a higher-level Lisp-like syntax, disassembling compiled code, and running CLVM programs. The current version is 0.4.10, and the library is actively maintained with frequent minor releases to support new Python versions and improve compatibility with the broader Chia ecosystem.","status":"active","version":"0.4.10","language":"en","source_language":"en","source_url":"https://github.com/Chia-Network/clvm_tools","tags":["clvm","chia","blockchain","compiler","lisp","smart-contracts"],"install":[{"cmd":"pip install clvm-tools","lang":"bash","label":"Install core library"},{"cmd":"pip install clvm-tools[clvm_rs]","lang":"bash","label":"Install with CLVM_RS backend for performance"}],"dependencies":[{"reason":"Core CLVM primitives and Program object representation.","package":"clvm","optional":false},{"reason":"Provides a high-performance Rust-based backend for CLVM compilation and execution, significantly speeding up operations. Highly recommended.","package":"clvm_rs","optional":true},{"reason":"An optional, performance-oriented Rust implementation used by clvm-tools for the 'run' personality.","package":"clvm_tools_rs","optional":true}],"imports":[{"note":"The canonical import path is `clvm_tools.binutils` after installation, despite the source code's nested `clvm_tools/clvm_tools` directory structure.","wrong":"from clvm_tools.clvm_tools.binutils import assemble","symbol":"assemble","correct":"from clvm_tools.binutils import assemble"},{"note":"Used for running compiled CLVM programs with arguments.","symbol":"brun","correct":"from clvm_tools.binutils import brun"},{"note":"Used to convert compiled CLVM back into human-readable code.","symbol":"disassemble","correct":"from clvm_tools.binutils import disassemble"}],"quickstart":{"code":"from clvm_tools.binutils import assemble, brun\nfrom clvm.Program import Program\n\n# A simple CLVM program that adds 1 to its argument\nclvm_source_code = \"(mod (A) (+ A 1))\"\n\n# Compile the CLVM source code\ncompiled_program_bytes = assemble(clvm_source_code)\nprint(f\"Compiled CLVM (hex): {compiled_program_bytes.hex()}\")\n\n# Define the arguments for the program (e.g., A = 5)\nprogram_arguments = Program.to((5,))\n\n# Run the compiled program with the arguments\n# `brun` can leverage clvm_rs if installed for better performance.\nresult = brun(compiled_program_bytes, program_arguments)\n\nprint(f\"Result of program with A=5: {result.as_int()}\")\n","lang":"python","description":"This quickstart demonstrates how to compile a basic CLVM program using `assemble` and then execute it using `brun`. It shows how to pass arguments to the CLVM program and interpret the result. For production use, consider installing `clvm-tools` with the `clvm_rs` extra for performance."},"warnings":[{"fix":"Install `clvm-tools` with the recommended performance dependencies: `pip install clvm-tools[clvm_rs]`.","message":"Performance of CLVM execution can be significantly slower without the `clvm_rs` backend. The `clvm-tools` library defaults to a pure Python backend unless `clvm_rs` (or `clvm_tools_rs`) is installed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `clvm-tools` and `clvm_rs` versions are compatible. It's often best to install `clvm-tools` using its `clvm_rs` extra (`pip install clvm-tools[clvm_rs]`) to ensure compatible versions are pulled in. Pin dependency versions in your `requirements.txt`.","message":"Compatibility with `clvm_rs` can be sensitive to version mismatches. Upgrading `clvm_rs` independently of `clvm-tools` might lead to runtime errors or unexpected behavior due to API changes.","severity":"breaking","affected_versions":"0.4.7 and earlier versions often experienced this; ongoing risk."},{"fix":"Develop CLVM code incrementally, test small components, and leverage `disassemble` to understand the compiled output. Refer to the official CLVM documentation for syntax specifics.","message":"Debugging syntax errors in CLVM code can be challenging as error messages from `assemble` might be terse or difficult to pinpoint to the exact line/token in complex programs.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"The correct import path for installed packages is `from clvm_tools.binutils import ...`. The nested `clvm_tools` folder is part of the internal source structure, not the importable package name.","cause":"Attempting to import modules based on the repository's internal folder structure rather than the installed package's top-level module.","error":"ModuleNotFoundError: No module named 'clvm_tools.clvm_tools.binutils'"},{"fix":"Ensure your CLVM program's return value is handled correctly by `brun` or subsequent operations. Verify that arguments passed to `brun` are correctly wrapped in `clvm.Program.to((arg1, arg2, ...))`.","cause":"Attempting to execute a CLVM program that returns an invalid type or when program arguments are incorrectly formatted for the CLVM runtime.","error":"TypeError: 'Program' object is not callable"},{"fix":"Carefully review your CLVM source code for typos, incorrect Lisp syntax (e.g., mismatched parentheses), or invalid opcodes. Use a CLVM linter or debugger if available, and consult official CLVM specifications.","cause":"The input CLVM source code contains a syntax error, an undefined opcode, or other structural issues preventing successful compilation.","error":"ValueError: CLVM compilation failed: ..."}]}