Install Pain001: pip, Docker and First Validated File

Pain001 runs on Python 3.10, 3.11, and 3.12 (each version tested in CI) on macOS, Linux, and Windows. Install what you need; every optional capability is an extra, so the base install stays lean.

01. PyPI#

What you need	Command
Core CLI & Python library	`pip install pain001`
REST API microservice (FastAPI + Uvicorn)	`pip install "pain001[api]"`
Parquet ingestion (PyArrow)	`pip install "pain001[parquet]"`
PGP-encrypted input files (`.gpg` / `.asc`)	`pip install "pain001[gpg]"`
Redis-backed async job queue for the API	`pip install "pain001[redis]"`
OpenTelemetry tracing	`pip install "pain001[otel]"`
Built-in minimal MCP / LSP servers	`pip install "pain001[mcp]"` / `"pain001[lsp]"`

Companion packages install separately and are versioned independently:

pip install pain001-loader-xlsx    # Excel ingestion (auto-discovered plugin)
pip install pain001-loader-mt101   # SWIFT MT101 parsing library
pip install pain001-mcp            # Full 17-tool MCP server for AI agents
pip install pain001-lsp            # Full six-feature editor language server

Verify the install and explore the message catalogue:

pain001 --version
pain001 versions          # list all 11 supported message definitions
pain001 init pain.001.001.09   # scaffold a starter CSV template

02. Docker#

Multi-architecture images (linux/amd64, linux/arm64) are published to GitHub Container Registry. The container runs as a dedicated non-root user.

# Generate XML from a local CSV
docker run --rm -v "$PWD:/data" -w /data \
  ghcr.io/sebastienrousseau/pain001:latest \
  generate -t pain.001.001.09 -d payments.csv -o out/

# Launch the REST API
docker run --rm -p 8000:8000 \
  ghcr.io/sebastienrousseau/pain001:latest \
  serve --host 0.0.0.0 --port 8000

03. Locked-down environments#

Bank and treasury environments often prohibit dynamic plugin loading. Two controls exist for exactly that case:

PAIN001_DISABLE_PLUGINS=1 disables all third-party plugin discovery; only bundled loaders run.
pain001 plugins list / pain001 plugins show <name> make every discovered plugin auditable before first use.

Everything executes locally. No package in the suite phones home, calls a SaaS API, or moves payment data off the host.

04. First file in three commands#

pip install pain001
pain001 init pain.001.001.09 -o work/
pain001 -t pain.001.001.09 -d work/template.csv -o work/ --dry-run

--dry-run validates against the JSON Schema, the XSD, and (with --scheme) a SEPA or cross-border rulebook without writing output. Exit code 0 means the file passed those checks: the schema, and the scheme rulebook where selected. Your bank's own profile and channel rules are separate, and still require bank testing. Drop --dry-run to write the XML.

Continue to the Technical Reference for every flag and endpoint, or the Quickstart FAQ for operational questions.