{"id":9622,"library":"coreir","title":"CoreIR Python Bindings","description":"Python bindings for CoreIR, an intermediate representation for hardware. This library provides a programmatic interface to build, manipulate, and analyze hardware circuits using Python. Currently at version 2.0.156, it maintains an active development pace with frequent updates, primarily leveraging a Rust-based CoreIR backend.","status":"active","version":"2.0.156","language":"en","source_language":"en","source_url":"https://github.com/leonardt/pycoreir","tags":["hardware description","HDL","compiler","bindings","digital design","IR","circuit design"],"install":[{"cmd":"pip install coreir","lang":"bash","label":"Install CoreIR"}],"dependencies":[],"imports":[{"note":"The PyPI package is 'coreir', despite the GitHub repository being named 'pycoreir'.","wrong":"import pycoreir","symbol":"coreir","correct":"import coreir"},{"note":"The primary entry point for CoreIR operations is an instance of coreir.Context.","symbol":"Context","correct":"context = coreir.Context()"}],"quickstart":{"code":"import coreir\n\n# Create a CoreIR context\ncontext = coreir.Context()\n\n# Define a simple module type (e.g., a 16-bit input and output)\ncoreir_type = context.Record({\n    \"in\": context.BitIn().Arr(16),\n    \"out\": context.Bit().Arr(16)\n})\n\n# Create a new module named 'my_adder' with the defined type\nmodule = context.Gettop().new_module(\"my_adder\", coreir_type)\n\n# Create a definition for the module, where instances and connections will be placed\nmodule_def = module.new_definition()\n\n# Get the 'add' generator and create an instance of a 16-bit adder\nadd16 = context.get_generator(\"coreir.add\").get_instances({\"width\": 16})[0]\nmodule_def.add_instance(\"add_inst\", add16)\n\n# Connect the module's input port to the adder instance's input\nmodule_def.connect(module_def.get_port(\"in\"), \"add_inst.in\")\n\n# Connect the adder instance's output to the module's output port\nmodule_def.connect(\"add_inst.out\", module_def.get_port(\"out\"))\n\n# Set the definition for the module\nmodule.set_definition(module_def)\n\n# Verify the module's type system (optional, but good for validation)\nmodule.type.verify()\n\nprint(f\"Successfully created CoreIR module: {module.name}\")\n# print(f\"Module definition:\n{module_def.str()}\") # Uncomment to see the generated IR","lang":"python","description":"This quickstart demonstrates how to initialize a CoreIR context, define a module's interface, create a module definition, add an instance of a built-in generator (an adder), and connect the ports, resulting in a simple 16-bit adder module."},"warnings":[{"fix":"Ensure a clean environment and reinstall with `pip install coreir`. Refactor code to use the latest API, consulting `pycoreir.readthedocs.io`.","message":"The underlying CoreIR library underwent a significant rewrite from C++ (CoreIR 1.x) to Rust (CoreIR 2.x). Python bindings for versions 2.x are incompatible with previous versions, requiring code migration for users coming from very old 'pycoreir' installations.","severity":"breaking","affected_versions":"< 2.0.0 (and associated older pycoreir builds)"},{"fix":"Always use `pip install coreir` for installation and `import coreir` in your Python code.","message":"The GitHub repository is named `leonardt/pycoreir`, but the official PyPI package for installation is `coreir`. Attempting `pip install pycoreir` or `import pycoreir` will fail.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always define types within the CoreIR context using its provided methods (e.g., `context.Bit()`, `context.Array()`, `context.Record()`).","message":"CoreIR uses a specific internal type system (e.g., `context.Bit()`, `context.BitIn().Arr(N)`). Directly using native Python types (like `int`, `list`, `bool`) where CoreIR types are expected will lead to type errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `context = coreir.Context()` is called once at the start of your program or function that interacts with CoreIR, and that the `context` object remains in scope for all subsequent CoreIR operations.","message":"CoreIR operations require an active `coreir.Context()` instance. Attempting to create modules, types, or instances without a valid context, or with a context that has gone out of scope, will result in errors.","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":"Change the import statement to `import coreir`. Ensure the package is installed via `pip install coreir`.","cause":"The user attempted to import the library using the repository name (`pycoreir`) instead of the correct PyPI package name (`coreir`).","error":"ModuleNotFoundError: No module named 'pycoreir'"},{"fix":"Use CoreIR context methods to define all types for ports and instances, e.g., `context.Bit()`, `context.BitIn().Arr(width)`, `context.Record(...)`.","cause":"A native Python type (e.g., `int`, `list`, `bool`) was provided where CoreIR expects its own type objects (e.g., `coreir.Bit()`, `coreir.BitIn().Arr(N)`).","error":"TypeError: Expected CoreIRType, got <class 'int'> (or similar for other Python types)"},{"fix":"Reinstall `coreir` in a fresh virtual environment (`pip install coreir --force-reinstall`). If the issue persists, verify system PATH and library search paths for the CoreIR shared library (e.g., `.so`, `.dll`, `.dylib`).","cause":"The underlying Rust CoreIR binary library, which the Python bindings depend on, could not be found or loaded. This can indicate a corrupted installation, environment issue, or path problem.","error":"RuntimeError: Failed to load CoreIR library. Ensure it is installed and in your PATH. (or similar DLL/shared library load error)"},{"fix":"Consult the latest CoreIR Python documentation (available at `pycoreir.readthedocs.io`) to update your code to the current API methods and parameter conventions.","cause":"The Python API for CoreIR has evolved, and method names (e.g., `newModule` vs `new_module`) or their signatures have changed between versions. The error indicates an attempt to use an old API method.","error":"AttributeError: 'Context' object has no attribute 'newModule' (or similar for outdated API calls)"}]}