Installation

epymorph is a Python library designed to be imported into your own code project, where your code project sets up, runs, and processes the results of disease simulations (or other epymorph-supported workflows). There are many ways to manage Python projects and many environments which run Python code. epymorph is designed to work in Jupyter Notebooks, Quarto documents, plain old Python scripts, and more.

epymorph is available on PyPI, so installation can be as simple as:

# If you use pip...
pip install epymorph

# If you use uv...
uv add epymorph

We do recommend using a virtual environment in each of your projects. If you’re not familiar with virtual environments, you can learn more about them here.

If you have epymorph installed (and if your virtual environment is active), you should be able to run this command to see the help text for epymorph’s command-line interface:

epymorph --help

Optional configuration

epymorph accepts configuration settings via environment variables. How you provide values differs between operating systems, and even on the same platform there can be several methods depending on your preference. If you’re using an IDE, that may have additional options.

You can also set values in Python code. This is okay for quick experiments, but has drawbacks. Putting configuration in your scripts can make them harder for others to use, as values may be specific to your machine. But most importantly: be careful you don’t share secret values or commit them to a code repository! (This is why other methods are preferred.)

import os

# For example:
# You could put this at the top of your program
# to set a value for the variable named CENSUS_API_KEY.
os.environ["CENSUS_API_KEY"] = "abcd1234"

Notable environment variables include:

EPYMORPH_CACHE_PATH: the path epymorph should use to cache files; this defaults to a location appropriate to your operating system for cached files.
CENSUS_API_KEY: your API key for the US Census API; this has no default. Features that fetch data from the US Census API may not work without this value.

Census API key

If you wish to use epymorph features that fetch data from the US Census API, you may request an API key here.

Common issues

These are some common issues users of epymorph have faced.

What is this cryptic error?

While we’re always working on improving the error messaging in epymorph, occasionally something particularly cryptic slips through the nets. Our best advice is to read the error trace carefully – your editor may be truncating the message and the root cause may be buried somewhere in the middle of the trace. You may find critical clues there!

SSL certificate problems on Mac

Mac users may run across an exception saying: ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate

Recent versions of Python on Mac do not install root certificates by default, but no worries this one is easy to fix. Find your Python installation directory. Inside should be a file named “Install Certificates.command”. Run it by double-clicking it. If that doesn’t immediately resolve the issue, try a system restart before other troubleshooting steps. (More info: python.org installation instructions.)