{"id":14826,"library":"pycel","title":"Pycel","description":"Pycel is a Python library designed to translate Excel spreadsheets into executable Python code, enabling them to run independently of Excel. It leverages a graph-based representation with caching and lazy evaluation for relatively fast execution. The library also supports visualizing the spreadsheet's dependency graph. It is currently in beta, version 1.0b30, with the last release in October 2021, and its release cadence has been irregular.","status":"active","version":"1.0b30","language":"en","source_language":"en","source_url":"https://github.com/stephenrauch/pycel","tags":["excel","compiler","spreadsheet","formula","graph","evaluation"],"install":[{"cmd":"pip install pycel","lang":"bash","label":"Install Pycel"}],"dependencies":[{"reason":"Required for date and time handling in Excel formulas.","package":"dateutil"},{"reason":"Used for building and traversing the dependency graph of Excel cells.","package":"networkx"},{"reason":"Provides numerical operations, especially for array formulas.","package":"numpy"},{"reason":"For reading and parsing .xlsx Excel files.","package":"openpyxl"},{"reason":"Likely used for serialization or configuration management.","package":"ruamel.yaml"},{"reason":"Optional: For visualizing the dependency graph.","package":"matplotlib","optional":true},{"reason":"Optional: For exporting graph visualizations, potentially to Graphviz formats.","package":"pydot","optional":true}],"imports":[{"symbol":"ExcelCompiler","correct":"from pycel import ExcelCompiler"},{"note":"While `from pycel import ExcelCompiler` works, direct import from `pycel.excelcompiler` is also commonly shown in examples.","wrong":"from pycel import ExcelCompiler","symbol":"ExcelCompiler","correct":"from pycel.excelcompiler import ExcelCompiler"}],"quickstart":{"code":"import os\nfrom openpyxl import Workbook\nfrom pycel import ExcelCompiler\n\n# Create a dummy Excel file for demonstration\nworkbook_name = 'example_spreadsheet.xlsx'\nwb = Workbook()\nws = wb.active\nws.title = \"Sheet1\"\nws['A1'] = 10\nws['A2'] = 20\nws['A3'] = '=A1+A2'\nws['B1'] = 'Hello'\nws['B2'] = '=CONCATENATE(B1, \" World\")'\nwb.save(workbook_name)\n\ntry:\n    # Compile the Excel spreadsheet\n    excel = ExcelCompiler(filename=workbook_name)\n\n    # Evaluate a cell\n    result_a3 = excel.evaluate('A3')\n    print(f\"Value of A3: {result_a3}\")\n\n    result_b2 = excel.evaluate('B2')\n    print(f\"Value of B2: {result_b2}\")\n\n    # Set a new value for A1 and re-evaluate A3\n    excel.set_value('A1', 100)\n    result_a3_updated = excel.evaluate('A3')\n    print(f\"Value of A3 after changing A1 to 100: {result_a3_updated}\")\n\nfinally:\n    # Clean up the dummy Excel file\n    if os.path.exists(workbook_name):\n        os.remove(workbook_name)\n","lang":"python","description":"This quickstart demonstrates how to create a simple Excel file, compile it using `pycel.ExcelCompiler`, and then evaluate cell values. It also shows how to dynamically update an input cell and observe the change in a dependent cell, illustrating `pycel`'s evaluation capabilities. The example cleans up the created Excel file afterwards."},"warnings":[{"fix":"Refer to the official GitHub repository for the latest documentation and changelog. Pin specific beta versions if stability is critical.","message":"Pycel is currently in beta (version 1.0b30) and was last released in October 2021. The API and behavior may still evolve, and breaking changes could occur in future non-beta or major releases without strict adherence to semantic versioning typical of stable libraries.","severity":"breaking","affected_versions":"1.0bX"},{"fix":"Understand that Pycel operates as a compiler and evaluator. If you need to write results back to an Excel file, you must use another library (e.g., `openpyxl`) and explicitly save the data.","message":"Pycel reads an Excel file and compiles its formulas into Python code for independent execution; it does NOT modify or write back to the original Excel `.xlsx` file. Changes made via `set_value` only affect the in-memory compiled model.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Extract and translate VBA logic into equivalent Python code. Pycel focuses solely on Excel formulas.","message":"VBA (Visual Basic for Applications) code embedded in Excel spreadsheets is not compiled by Pycel. Any logic implemented in VBA needs to be manually re-implemented in Python if its functionality is required in the Pycel model.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always call `excel.evaluate()` on at least one output cell of interest to trigger the compilation and graph construction before attempting to visualize or export the graph.","message":"Pycel employs lazy evaluation. The internal graph representing the spreadsheet's dependencies is not fully built or processed until a cell is explicitly evaluated using `excel.evaluate()`. Attempting to plot or export the graph before evaluation may result in an empty or incomplete graph.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the Pycel documentation or source code for a list of supported functions. If a required function is missing, it may need to be implemented or a workaround devised. For `OFFSET`, ensure all potentially referenced cells are part of the compiled model.","message":"The support for Excel functions in Pycel is driven by the developer's specific needs and may not be exhaustive. While common mathematical functions and operators are supported, some less frequently used or complex functions might be missing. The `OFFSET` function, in particular, can fail if a referenced cell is not already compiled.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[],"ecosystem":"pypi"}