Skip to content

Installation

Femora is released to PyPI and can also be installed directly from source for development workflows.

Requirements

Before installing Femora, make sure you have:

  • Python 3.9 or newer
  • pip
  • a normal scientific Python environment with permission to install packages

Femora depends on packages such as vtk, pyvista, scipy, h5py, meshlib, and trame, so a clean virtual environment is strongly recommended.

For most users, the standard installation path is:

pip install femora

This installs the core package and its required dependencies from PyPI.

Optional Extras

Femora exposes a few optional dependency groups depending on your workflow.

Jupyter Support

If you plan to use Femora heavily in notebooks:

pip install "femora[jupyter]"

METIS / Partitioning Support

If you need partition-related workflows that depend on pymetis:

pip install "femora[metis]"

Extended Local Tooling

If you want the broader optional set used for richer local development environments:

pip install "femora[all]"

Use this only when you actually want the larger optional stack.

Install From Source

If you are developing Femora itself, testing local changes, or working from the repository:

git clone https://github.com/GeotechUW/Femora.git
cd Femora
pip install -e .

For source development with optional extras:

pip install -e ".[all]"

An editable install is the right choice when:

  • you are modifying Femora source code
  • you are working on docs and examples together
  • you want local changes reflected immediately without reinstalling

Conda Workflow

If you prefer Conda, create an isolated environment first and then install Femora inside it.

Example:

conda create -n femora python=3.10
conda activate femora
pip install femora

If you are working from the repository and want to start from the included environment file:

conda env create -f environment.yml
conda activate myenv
pip install -e .

If you rename the environment in environment.yml, activate that name instead of myenv.

Verify the Installation

The quickest verification is to import Femora in Python:

python -c "import femora; print(femora.__name__)"

You can also check that the main workflow entry is available:

from femora.core.model import Model

model = Model()
print(type(model).__name__)

Local Documentation Workflow

If you are working on the website or docs locally, Femora's repo includes a local workflow helper.

For fast website editing:

python run_local.py --mode website

For the full combined site check:

python run_local.py --mode full

The full mode builds:

  • the website
  • the generated API docs
  • the merged local documentation site

Common Notes

Use a Virtual Environment

Do not install Femora into a crowded global Python environment if you can avoid it. vtk, pyvista, and related packages are easier to manage inside a dedicated environment.

PyPI vs Source

Use PyPI when you want a clean released version.

Use source installation when you want:

  • the latest local code
  • editable development
  • docs or website work
  • contribution workflows

Interactive Plotting

Femora supports in-code inspection and plotting workflows. If your local environment is missing visualization-related dependencies, install the optional extras you need or use the richer source-development environment.

Next Steps

After installation:

  1. read the Getting Started guide
  2. open the Examples & Tutorials page
  3. use the API Reference when you need exact manager, class, or method behavior