Getting started

How to bootstrap a project with mxmake

Essential Requirements

All installation methods require:

Choose Your Installation Method

mxmake supports two installation approaches:

Option 2: Traditional pip-based

Requirements: Python 3.10+ with venv module

  • Ubuntu/Debian: sudo apt install python3 python3-venv

  • macOS: Python 3.10+ from python.org

  • Windows: Python 3.10+ from python.org

Install mxmake:

mkdir myproject && cd myproject

# Option A: Global installation
pip install mxmake

# Option B: In a virtual environment
python3 -m venv venv
. venv/bin/activate  # On Windows: venv\Scripts\activate
pip install mxmake

Bootstrap your project:

mxmake init

# Answer prompts interactively
# This creates mx.ini and Makefile

make install

After Initialization

Both methods create:

  • Makefile - Generated by mxmake with your selected topics/domains

  • mx.ini - Configuration for mxdev (if you selected that option)

To update an existing Makefile without interactive prompts, run mxmake update.

Monorepo Support

mxmake supports monorepo setups where your Python project lives in a subdirectory while the Makefile stays at the repository root. This is useful when you have multiple applications (e.g., frontend + backend) in one repository. You may need to edit mx.ini and set requirements-in or main-package to the subfolder.

Example Directory Structure

myrepo/                    # Repository root
├── Makefile               # Generated by mxmake (at root)
├── mx.ini                 # mxdev config (at root)
├── .venv/                 # Virtual environment (at root)
├── .mxmake/               # Generated files (at root)
├── sources/               # mxdev packages (at root)
├── frontend/              # Frontend application
│   └── package.json
└── backend/               # Python project in subdirectory
    ├── pyproject.toml
    ├── src/
    │   └── myapp/
    └── tests/

Setup Methods

Method 2: CLI Flag

Specify the project path explicitly:

uvx mxmake init --project-path-python backend

Method 3: Preseed File

Include in your preseed YAML:

topics:
  core:
    base:
      PROJECT_PATH_PYTHON: backend

Then run:

uvx mxmake init --preseeds preseed.yaml

What Happens

When PROJECT_PATH_PYTHON is set:

  1. Makefile: References Python package files with the correct path

    • Looks for backend/pyproject.toml instead of ./pyproject.toml

  2. mx.ini: Configure test/coverage paths relative to repository root

    • Set mxmake-test-path = backend/tests and mxmake-source-path = backend/src

  3. GitHub Actions: Cache uses correct path

    • cache-dependency-glob: "backend/pyproject.toml"

Configuration

The PROJECT_PATH_PYTHON setting appears in your Makefile:

# Path to Python project relative to Makefile (repository root)
PROJECT_PATH_PYTHON?=backend

In your mx.ini, specify paths relative to the repository root (including the project path):

[settings]
mxmake-test-path = backend/tests
mxmake-source-path = backend/src

Important

Future-proofing: This setting is named PROJECT_PATH_PYTHON to allow for future PROJECT_PATH_NODEJS support in multi-language monorepos.

How to change the settings

The Makefile consists of three sections:

  1. Header with configured topics/domains

  2. Settings (for customization)

  3. Makefile logic (do not edit)

The header is not intended for editing, thus it does not cause any harm by adding or removing domains here. It is considered during the execution of mxmake init respective mxmake update. Added or removed topics are checked or unchecked accordingly on the next run.

The settings section is where customization is happening. Domains can provide configurable settings. Setting names must be unique among all domains. Thus they are usually prefixed.

Each setting provides a description and an optional default value.

For details read the chapter on topics and it’s domains.

Do not add custom settings to settings section. They will be lost on next mxmake init respective mxmake update run.

Python Package Installer

mxmake supports two package installers:

UV (Recommended): Modern, fast package installer that can automatically download Python.

  • Set PYTHON_PACKAGE_INSTALLER=uv in the Makefile

  • UV is auto-detected if installed globally, or installed locally in the venv

  • Specify UV_PYTHON explicitly (e.g., 3.14) to control which Python version UV downloads

pip (Default): Traditional package installer, requires Python pre-installed.

  • Works with any Python 3.10+ installation

  • Uses the Python specified in PRIMARY_PYTHON setting

Example UV configuration:

PYTHON_PACKAGE_INSTALLER?=uv
UV_PYTHON?=3.14  # UV downloads Python 3.14 automatically

Example pip configuration:

PRIMARY_PYTHON?=python3.12
PYTHON_PACKAGE_INSTALLER?=pip  # Default

Important

When using UV, always set UV_PYTHON explicitly. While it currently defaults to PRIMARY_PYTHON for backward compatibility, relying on this default is not recommended and may change in future versions.

Note

With UV + UV_PYTHON explicitly set:

  • PRIMARY_PYTHON is not needed (only used as UV_PYTHON default)

  • PYTHON_MIN_VERSION is not needed (validation skipped with global UV)

These settings are only required for pip-based workflows.

How to use on the Windows operating system

mxmake works excellent on Windows!

On Windows it needs a Bash shell. Fortunately the GIT VCS comes with the a fully function Bash, the git-bash. Please follow GIT’s official installation instructions.

Install make as described here

Further you need a Python >=3.10 installation..

Dependent on the topics and domains you use, you may need to install additional software, but this is no different from Linux/OSX.

Troubleshooting

UV not found error

If you get an error that UV is not found, install it. See the official UV installation guide for detailed instructions.

# Global installation (recommended)
pip install uv

# Or use the official installer
curl -LsSf https://astral.sh/uv/install.sh | sh

After installation, run mxmake update to regenerate the Makefile.

Python version mismatch

If UV uses a different Python version than expected, explicitly set UV_PYTHON in your Makefile settings:

UV_PYTHON?=3.14

Then run make install again.

Tests not running

If make test fails with “command not found”, ensure the test runner script was generated:

ls .mxmake/files/run-tests.sh

If missing, check that your mx.ini includes mxmake-templates = run-tests and run make install to regenerate files.

Make command not found

On Ubuntu/Debian: sudo apt install make On macOS: Install Xcode Command Line Tools: xcode-select --install On Windows: See installation instructions

Settings not taking effect

Settings are only applied when you explicitly set them. If a setting has ?=, it uses the default unless overridden.

Example: Change PRIMARY_PYTHON?=python3.12 to PRIMARY_PYTHON=python3.14 (remove the ?) to force that value.

Note that environment variables always override Makefile settings. Check if a setting is defined in your shell environment:

echo $PRIMARY_PYTHON

After changing settings, run make install to apply them.

Regenerating the Makefile

To add or remove domains without interactive prompts, use:

mxmake update

This preserves your current settings and updates the Makefile logic. To start fresh interactively, use mxmake init.

After upgrading mxmake to a newer version, run mxmake update to apply new features and improvements from the upgraded version.