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 (RECOMMENDED!)...
uv add epymorph

We 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

Or with uv, you would usually run commands like:

uv run epymorph --help

Python version support

epymorph currently supports Python versions 3.11 and 3.12. While epymorph may work with newer versions of Python, this is not tested and not guaranteed. And you would likely need to build certain dependencies from source to be able to install the package. We are working to support newer Python versions in the near future, but for now we recommend sticking with a supported Python. The epymorph project takes a cautious approach to version upgrades because we value simulation result stability more highly than staying at the cutting edge of software versioning.

The easiest way to set up a project with a specific Python version is using uv (a tool from Astral). If you do not have your own preferences on how to manage python projects, we strongly recommend you start with uv!

# In a new project directory...
uv init --python 3.12
uv add epymorph

If you prefer to use venv, make sure to initialize the virtual environment with the appropriate Python executable. For example (Mac/Linux):

# In a new project directory...
python3.12 -m venv .venv
source .venv/bin/activate
pip install epymorph

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:

  • 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.
  • EPYMORPH_CACHE_PATH: the path epymorph should use to cache files; this defaults to a location appropriate to your operating system for cached files.
  • EPYMORPH_CACHE_DISABLED: (added v1.1.0) set this to “true” to completely disable the use of the cache.
  • EPYMORPH_CACHE_DISABLED_PATHS: (added v1.1.0) set this to a list of one or more paths (separated by semicolons) to selectively disable the cache for certain cases. Every system that uses the cache has an associated path (relative to the cache root) at which they store files. If that path is in this list, reading and writing those files from the cache will be disabled. Cache paths usually are related to the Python module involved; for example, the PRISM ADRIO is in the epymorph.adrio.prism module and so it uses adrio/prism as its cache path.

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.)