Getting Started with Mathpix Python SDK

This guide explains how to install the Mathpix Python SDK (mpxpy) and authenticate with Mathpix services.

Installation

The SDK is available via the Python Package Index (PyPI). Install it with:

pip install mpxpy

Alternatively, to install directly from the GitHub repository for development purposes:

# Clone the repository
git clone https://github.com/Mathpix/mpxpy.git
cd mpxpy

# Install in development mode
pip install -e .

Authentication

You’ll need a Mathpix API app_id and app_key to use this client. You can get these from the Mathpix Console.

Set your credentials by either:

Using environment variables
Passing them directly when initializing the client

MathpixClient will prioritize auth configs in the following order:

Passed through arguments
The ~/.mpx/config file
ENV vars located in .env
ENV vars located in local.env

Using environment variables

Create a config file at ~/.mpx/config or add ENV variables to .env or local.env files:

MATHPIX_APP_ID=your-app-id
MATHPIX_APP_KEY=your-app-key
MATHPIX_URL=https://api.mathpix.com  # optional, defaults to this value

Passing credentials directly

from mpxpy.mathpix_client import MathpixClient

client = MathpixClient(
    app_id="your-app-id",
    app_key="your-app-key"
)

Then initialize the client:

from mpxpy.mathpix_client import MathpixClient

# Will use ~/.mpx/config or environment variables
client = MathpixClient()

# Will use passed arguments
client = MathpixClient(
    app_id="your-app-id",
    app_key="your-app-key"
)

You can also pass a file_url if the PDF is hosted online instead of providing a local file_path.
Supported output formats include pdf, docx, md, and mmd.
You can specify desired formats at the time of upload by using the formats parameter.