pycel compiles an Excel spreadsheet into a Python dependency graph

Getting a spreadsheet's logic out of Excel

pycel is a small Python library that can translate an Excel spreadsheet into executable Python code which can be run independently of Excel. That framing is the whole product, and it is narrower and more interesting than it sounds.

A financial model, a risk calculation or a pricing sheet is often a spreadsheet that has grown a piece of logic nobody wants to maintain twice. The formula lives in cells, the workbook is passed around, and the only way to evaluate it is to open Excel, which means a Windows or macOS desktop, a licensed installation, and a human. pycel takes that workbook and produces Python code that computes the same thing on a server, in a container, or in a test.

The audience is therefore not a data analyst but an engineer who has inherited a spreadsheet as a piece of business logic. The project description says it plainly: compile excel spreadsheets to python code and visualizing them as a graph.

The licence is GPL-3.0, the primary language is Python, the default branch is master, the last push was on 2026-10-17, and the repository publishes no GitHub releases, with the changelog kept in CHANGES.rst and the package published to PyPI.

The optional dependencies hint at what the tool is for. matplotlib and pydot are both optional, and they are the drawing and graph-export libraries, so the analysis of the compiled model is a first-class use case rather than an afterthought.

The graph underneath the generated code

The Python code pycel produces is based on a graph, and it uses caching and lazy evaluation to keep execution reasonably fast. That single design choice explains most of the project's behaviour, including its strengths and its stated weaknesses.

A spreadsheet is naturally a dependency graph. Cell B3 depends on B1 and B2, B2 depends on a formula referencing other cells, and a full model is a directed acyclic graph of thousands of nodes. pycel reads that structure out of the workbook and turns it into Python code whose dependencies are explicit.

The caching matters because a spreadsheet recomputes far more than it needs to. A user edits one input and Excel recalculates the dependents, but a naive translation to Python that evaluates every formula on every call would be much worse. The lazy evaluation means a value is computed when it is first needed, and the cache means it is computed once.

And because the structure is a graph rather than a pile of functions, it can be exported and analyzed with tools like Gephi, as the README says, with an example in the repository as an illustration. That is a genuinely useful artefact: the dependency graph of a spreadsheet tells you what a change to a cell will affect, and it tells you which parts of a workbook are tangled.

The implementation leans on the standard scientific Python stack. The required libraries are dateutil, networkx, numpy, openpyxl and ruamel.yaml, and networkx is the graph library the whole design sits on.

What it can evaluate, and how closely it matches Excel

The project documentation is unusually frank about coverage, listing the good, the bad and the ugly in separate sections.

What works: all the main mathematical functions such as sin, cos and atan2, the operators including addition, division and exponentiation, ranges such as A5:D7, and functions like MIN, MAX, INDEX, LOOKUP and LINEST. The codebase is described as small, relatively fast, and something that should be easy to understand and extend.

The accuracy claim is specific enough to be useful. The author states that he has tested it extensively on spreadsheets with 10 sheets and more than 10000 formulae, that calculating the equations takes about 50ms in that case, and that the results agree with Excel up to 5 decimal places. Those are the author's own figures from his own workbooks, not an independent benchmark, and the 5 decimal places figure is a useful thing to keep in mind when a result is compared against Excel in a different context.

The parsing itself has a pedigree. The documentation credits Robin Macharg's Python port of Eric Bachtal's Excel formula parsing code as the original enabler, and notes that the code currently uses a tokenizer of similar origin from the openpyxl library, which is the same library that reads the workbook in the first place.

The practical takeaway is that pycel is a translator for a well-behaved subset of Excel, and the subset is the formulas in the author's own spreadsheets.

The gaps the author documents himself

The bad section of the README is the most useful part of the documentation, and it names three concrete limits.

The first is coverage. Development has been driven by the particular spreadsheets the author needs to handle, so he has only added support for the functions he needs, while noting that it should be straightforward to add support for others. The corollary is that an unsupported function in your workbook is not a bug report, it is a gap in the library.

The second is that cell references are supported, so a function like OFFSET works, but there is a catch: if a cell is not already compiled in, the function can fail. That is the sharp edge. A function that reaches outside the compiled region does not return a wrong answer, it fails, and whether it fails depends on which cells happened to be pulled into the graph.

The third is VBA. Any VBA code is not compiled and has to be re-implemented manually on the Python side. For a workbook whose logic lives in macros rather than in cells, pycel does not help at all, and no amount of function support changes that.

The ugly section is about performance. The graph-based code is fast enough for the author's purposes, but the author says that to make it truly fast you would probably replace the graph with a dependency tracker based on sparse matrices or something similar. That is an unusual thing for a project to say about its own core design, and it is a fair signal that the graph is the right structure for analysis and the wrong structure for maximum throughput.

Running the example and reading the graph

The usage section of the README is short. You download the library and run the example file, and the repository ships both parts of that: an example spreadsheet, example.xlsx, and example.py.

For exploring the tool without installing anything, the documentation points at a binder notebook, which gives an interactive session in the browser with the example workbook already loaded.

Working on the code itself is the usual Python packaging route. The setup script's own instructions describe installing a link for development work:

    pip install -e .

The setup script also documents the release path, building a distribution with:

    python setup.py sdist bdist_wheel

and running the test suite with tox, with the tests themselves driven by pytest through the test_suite setting and the extra requirements read from test-requirements.txt.

The graph is the part you analyse rather than just run. With matplotlib and pydot installed, the compiled model can be drawn, and the Gephi route in the README is the one for larger models, where a picture of the dependency structure tells you more than a list of functions does.

Running pycel inside Excel through PyXLL

There is an unusual option in the project, which is to run pycel as an Excel add-in using PyXLL.

The instructions are short. Place pyxll.xll and pyxll.py in the lib directory, then add the xll file to the Excel Addins list as explained in the PyXLL documentation.

What this gives you is the reverse of the usual direction. Normally pycel takes a workbook and produces Python. With the add-in, the Excel instance itself calls into pycel to evaluate the compiled graph, which means the workbook keeps its formulas and its UI while the evaluation runs in the Python graph instead of in Excel's calculation engine.

That is attractive for a specific reason. It is the only arrangement where the two stay in sync, because there is one model, the workbook, and the graph is a cached view of it. It is also the arrangement with the most moving parts, since it needs a native Excel add-in, PyXLL installed on the machine, and a lib directory inside the project.

The repository keeps a lib/ directory, which is where those files are expected to go, and the example/ directory provides a workbook and a script you can point the add-in at.

A small library with a long history and an unversioned release record

A few administrative details are worth knowing before you depend on this.

The repository has no GitHub releases, so there is no tag to pin and no binary to download. The package is published to PyPI, and the changelog lives in CHANGES.rst in a keep-a-changelog format, with the setup script reading it to build the long description that appears on the PyPI page. The version itself is kept in a single file, src/pycel/version.py, and the setup script executes that file to read the version, which is why the release instructions say to update that file and the changelog together.

The dependency list in the setup script starts with networkx pinned to a range below 2.7, which is a sign of an older constraint, and numpy. The rest of the required libraries are the ones named in the README.

One detail stands out and may confuse you. The setup script's url points at github.com/stephenrauch/pycel, and so do the tracker link and the requirements badge, even though the repository itself is dgorissen/pycel. The project moved, and the packaging metadata still refers to the older location. The code, the tests and the changelog are all in the current repository, so this is a link that has not been updated rather than a second copy of the project.

For maintenance, the useful signal is the last push on 2026-10-17 and the presence of a GitHub Actions directory alongside the older Travis configuration, which suggests the project is still being worked on rather than sitting still.

Editorial conclusion

pycel suits a team that needs a spreadsheet's logic to run in a server process rather than in Excel, for instance to re-price a model on a schedule, and it is the wrong choice when the workbook relies on functions the library has not implemented or on macros, because VBA is never compiled and has to be re-implemented by hand. Before adopting it, check the function list against your own workbook and confirm that the cells OFFSET would reach are already compiled in, since the author documents that case as a known failure mode.

Frequently asked questions

Official sources

1. dgorissen/pycel on GitHub
2. Issues
3. License: GPL-3.0
4. README