Welcome to snakehouse’s documentation!

What is snakehouse?

Snakehouse is a package that helps you put multiple .pyx files in a single Python so/DLL, so that each is importable by Python as if they were just plain .py files.

How do I install it?

Do it via

pip install snakehouse

All dependencies will be installed automatically.

Mandatory reading and limitations

Take a look at example on how to multi-build your Cython extensions.

Don’t place modules compiled that way in root .py file’s top level imports. Wrap them in a layer of indirection instead!

So if your module is called example, make a start_example/__main__.py with the following code:

if __name__ == '__main__':
    from example import run

Or however you do start your application.

This applies to unit tests as well!

When something goes wrong (eg. the application throws an unhandled exception) the built module has a tendency to dump core. Try to debug it first by passing dont_snakehouse=True to your modules in the debug mode.

Also note that if you are compiling in dont_snakehouse mode then your modules should have at least one of the following:

  • a normal Python def

  • a normal Python class (not cdef class)

  • a line of Python initialization, eg.

a = None


import logging

logger = logging.getLogger(__name__)

Otherwise PyInit won’t be generated by Cython and such module will be unimportable in Python. Normal import won’t suffice.


Contributions are most welcome. Just add yourself to CONTRIBUTORS.md list at your pull request. At this moment most pressing issues are the segfaulting problem, where snakehouse-built libraries segfault the Python interpreter when there’s an unhandled exception (sometimes, I can’t really seem to pinpoint the problem source).

Try to unit test what you’re changing, but that is by no way a requirement.

Indices and tables