Installation

Requirements

Python 3.11, 3.12, or 3.13
MNE-Python 1.10.2
NumPy 2.1.3
SciPy >= 1.15.3
scikit-learn >= 1.4.2
uv (contributors only)

Install from PyPI (Recommended)

For normal usage, install FACETpy from PyPI. This is sufficient for running your own scripts and the repository examples.

pip install facetpy

The package name on PyPI is facetpy; import it in Python as facet.

Full Setup from Source (Contributing, Example Datasets/Scripts, Early Access to features)

FACETpy is managed with uv.

Unix (macOS/Linux)

For contributors on Unix-like systems, the quickest setup is the bootstrap URL:

curl -fsSL https://raw.githubusercontent.com/H0mire/facetpy/main/scripts/bootstrap.sh | sh
cd facetpy

You can also run the installer script in an existing clone:

./scripts/install.sh

Other platforms (including Windows)

For contributors outside Unix-like shells, use uv directly:

git clone https://github.com/H0mire/facetpy.git
cd facetpy
uv sync --locked

The Unix ./scripts/install.sh script:

checks for Python 3.11/3.12/3.13
checks whether uv is installed
prompts to install uv if missing
runs uv sync --locked

The bootstrap script:

clones FACETpy into ./facetpy
runs ./scripts/install.sh inside that clone

Manual uv setup (contributors):

uv sync --locked

Run contributor commands inside the uv environment (Unix and Windows):

uv run pytest

Optional extras (Unix and Windows):

uv sync --extra deeplearning     # TensorFlow-based extras
uv sync --extra notebooks        # Jupyter notebook support
uv sync --extra gui              # PyQt6 GUI components
uv sync --extra docs             # Sphinx + MyST documentation toolchain
uv sync --all-extras             # all optional dependencies

Development Installation

The standard uv sync includes development dependencies such as pytest and ruff. Documentation tooling (sphinx, myst-parser) is installed via --extra docs.

Optional Components

C Extension for ANC

Strong recommendation: compile the FastRANC C extension once after installing. ANC runs significantly faster with it.

Without uv:

python -m facet.build

With uv:

uv run build-fastranc

This will create:

libfastranc.so (Linux)
libfastranc.dylib (macOS)
fastranc.dll (Windows)

If the C extension is not compiled, ANCCorrection falls back to a slower Python implementation and the rest of the toolbox still works.

Verify Installation

To verify your installation:

import facet
print(facet.__version__)

This should print the version number without errors.

Troubleshooting

MNE-Python Issues

If you encounter issues with MNE-Python installation:

pip install --upgrade mne

See MNE installation guide for platform-specific instructions.

Import Errors

If you get import errors, reinstall dependencies:

pip install --upgrade --force-reinstall facetpy

For contributor/source environments, run:

uv sync --locked