Skip to content

Installation

Time: about 5 minutes, plus the download · You need: Python 3.11, 3.12 or 3.13 on Windows or Linux (x86-64). You'll end with: ml4 installed in its own environment, with the extras you need.

ml4 is published on PyPI as compiled wheels. You install parleml-ml4 and import parleml_ml4. The core already includes AutoGluon Tabular, PyTorch, the tree boosters, the glass-box models, association mining and PyOD anomaly detection.

Only scoring a model from ParleML?

You don't need this page. A registered model's scoring package carries a requirements.txt that pins the exact ml4 it needs, with the right extras. Install that instead: see Use your model in Python.

1. Create an environment

uv venv --python 3.12

python3.12 -m venv .venv
source .venv/bin/activate

py -3.12 -m venv .venv
.venv\Scripts\Activate.ps1

2. Install ml4

uv pip install parleml-ml4

pip install parleml-ml4

Add the extras you need in square brackets, separated by commas. For example, for forecasting with every backend:

pip install "parleml-ml4[forecasting,forecasting-autogluon]"

3. Check it

import parleml_ml4
from parleml_ml4 import AutoSupervised, Ml4Config, DataConfig, Tasks

print(parleml_ml4.__version__)

Wheels are platform-specific

The wheels are compiled native code, so each one targets one operating system, CPU and Python version (for example cp312 on win_amd64). pip picks the right one. If it finds none, check your Python version (3.11 to 3.13) and platform. On macOS, run ParleML in Docker instead: see Run ParleML.

Optional extras

The core covers classification, regression, recommendation, association mining, anomaly detection and most feature engineering. Install an extra only for what it enables.

Extra Enables
forecasting Forecasting: the stats backend (statsforecast) and the tree backend's Optuna search
forecasting-autogluon AutoGluon-TimeSeries 1.6.3, used by the tree, foundation (Chronos) and autogluon backends. Install it together with forecasting.
unsupervised UMAP projection and text-clustering embeddings for clustering. Anomaly detection needs no extra.
ltr Optuna search for learning-to-rank. LightGBM and CatBoost are already in the core.
embeddings Local neural text embeddings (sentence-transformers). Embeddings through a provider connection need no extra.
stateless The personal-name corpus (about 150 MB) for name features. Includes embeddings.
mlops MLflow logging and registration
realtime The Treelite fast-scoring accelerator
Details: what happens when an extra is missing

Optional dependencies are checked on the paths that use them. Some feature encoders and accelerators skip with a warning. A backend you request explicitly fails with an installation hint. Local embeddings and foundation models also need their weights, not only the Python package: Chronos weights are downloaded on first use and cached, so an offline fit needs its checkpoint cached in advance. See Troubleshooting.

Recommendation and the ranking metrics add no dependencies of their own. Association mining uses mlxtend from the core; there is no association extra.

Reference data for domain features

Two domain features use reference data:

Feature What to provide
IP geolocation (MaxMind GeoLite2) The .mmdb files are not shipped, for licensing reasons. Download them and set MAXMIND_DB_DIR to their folder. parleml_ml4.config.describe.describe_domains() reports whether they were found.
Postal codes (pgeocode) The GeoNames data is bundled (attribution required). Nothing to provide.

The Geography & reference data guide has the MaxMind download steps and the GeoNames attribution.

PyTorch: CPU or GPU

pip installs PyTorch from PyPI. On Windows that is the CPU build; on Linux it is the CUDA build, which adds several GB of NVIDIA libraries. To keep a Linux install CPU-only, install torch from PyTorch's CPU index first, then ml4:

pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install parleml-ml4

For a GPU on Windows, reinstall torch from the matching CUDA index. See GPU acceleration.

Details: working from a ParleML source checkout

Inside the ParleML repository, use the shared workspace environment rather than a separate install. From the repository root:

uv sync --python 3.12

This installs every workspace package, the forecasting stack and the development and documentation tools, with the repository's dependency overrides and CPU PyTorch index. Regenerate the configuration reference and build this site from the same checkout:

uv run python ml4/scripts/gen_config_reference.py
uv run mkdocs build --strict -f ml4/mkdocs.yml

The two development extras are dev (pytest, coverage, Ruff, pandas stubs) and docs (MkDocs Material, mkdocstrings).

Next

  • Quickstart: train and score a model in a dozen lines.