Installation

Prev: Part 1: Introduction

PyMFCAD is available on PyPI. The recommended installation method uses uv, with legacy venv/pip instructions provided for compatibility.

Choose one path below. If you already have an active environment, skip directly to the install step.

Why use uv?

uv is a fast, modern Python package manager that simplifies virtual environments and dependency management:

  • Installs packages significantly faster than pip
  • Automatically manages virtual environments
  • Provides a simpler, more reliable workflow for modern Python projects
  • Works as a drop-in replacement for pip in most cases

Python versions

PyMFCAD supports Python 3.10–3.14.

  1. (Optional) Create a new project directory: 
    mkdir my-mf-project && cd my-mf-project
  2. Install uv if you don't have it. Installation instructions can be found here.
  3. Create a virtual environment and install PyMFCAD: 
    uv venv
uv pip install pymfcad
  4. Quick verification (runs a built‑in demo): 
    uv run python -m examples.full_test

Option B — Install with venv and pip

  1. Create and activate a virtual environment:
    • macOS/Linux: 
      python3 -m venv env
source env/bin/activate
    • Windows:
      • Command Prompt: 
        python -m venv env
CALL env\Scripts\activate
      • Windows PowerShell: 
        python -m venv env
.\env\Scripts\Activate.ps1
  2. Install PyMFCAD from PyPI: 
    pip install pymfcad
  3. Quick verification (runs a built‑in demo): 
    python -m examples.full_test

Quick check

You should be able to run a demo without errors and see the visualizer open.

Developing from source

If you are working from the repository, use the Makefile targets below (requires uv).

  1. Clone or download the repository.
  2. In a terminal, change into the repository root.
  3. Use the targets below to install and run the project.

Makefile targets

  • make init — creates the virtual environment, installs Python packages, and installs JS dependencies
  • make build — builds the docs, Vite site, and packages with uv
  • make serve — updates docs, builds the Vite site, and serves the PyMFCAD webpage
  • make test — runs all PyTest test cases
  • make test-coverage — runs all PyTest test cases and outputs code coverage in htmlcov
  • make run <python file> — runs a Python file
  • make mem-profile <python file> — runs a Python file with heaptrack
  • make py-profile <python file> — runs a Python file with cProfile
  • make web-install — installs JS dependencies
  • make web-build — builds the Vite site
  • make clean — removes all build products

Release targets

For creating releases, the following targets are available (requires gh CLI):

  • make release-major — bumps major version, creates git commit, builds, and publishes GitHub release
  • make release-minor — bumps minor version, creates git commit, builds, and publishes GitHub release
  • make release-patch — bumps patch version, creates git commit, builds, and publishes GitHub release

Each release target will:

  1. Prompt whether this is a pre-release
  2. Open your default editor to collect release notes
  3. Bump the version in pyproject.toml and uv.lock
  4. Create a git commit with the version bump
  5. Run make clean and make build
  6. Create and publish a GitHub release with binaries

Testing releases:

To test the release process without committing/updating version or publishing, use: 

DRY_RUN=true make release-major
DRY_RUN=true make release-minor
DRY_RUN=true make release-patch

This runs through the entire workflow but creates a draft release on GitHub (not published).

GitHub CLI installation

The release targets require the gh CLI tool. Install it using your package manager:

macOS: 

brew install gh

Linux (Ubuntu/Debian): 

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

Fedora/RHEL: 

sudo dnf install gh

Other systems:

See the official gh installation guide.

After installing, authenticate with your GitHub account: 

gh auth login

Troubleshooting

Issue: pip install uv succeeds, but the uv command is not found.

Fix: Run pip show uv and add the reported install location to your PATH.

Issue: pip install pymfcad fails while building the manifold3d wheel.

Fix: Verify your Python version is supported (Python 3.10–3.14).

Next: Part 3: Using the Visualizer