Run inference

MCMC.js gives you two ways to run inference: mcmc run for a zero-config end-to-end workflow, and mcmc fit for the explicit spec-in, samples-out contract.

mcmc run: the front door

mcmc run <input> runs the whole workflow in one step: it fits, diagnoses, and records the run in the project store. The input can be any of four things, and the backend is detected from it:

• a model file (.jl for Turing or JuliaBUGS, .stan for Stan, .bugs for a program in BUGS syntax),
• a spec file (.toml / .json),
• a DoodleBUGS graph (.json), which is converted first, or
• a BUGS example folder, as the JuliaBUGS repository keeps them: model.bugs beside data.json, inits.json, and reference.json.

mcmc run model.jl --data data.csv --seed 42
mcmc run path/to/BUGSExamples/volume_1/rats

An example folder runs with its own data and published initial values, and stores the parameters plus the quantities the example published summaries for. Its run store is the nearest .mcmc above the current directory, never the folder itself, which may be a read-only artifact.

It prints the diagnostics table and verdict, and exits 0 on convergence, 2 if it ran but did not converge, or 1 on error.

Run it without an input on a terminal and it offers the model files it finds in the project, so you can pick one instead of typing a path. To explore what you already have, see Browse interactively.

Settings: flags over spec

When you run a model file directly, sampling settings come from flags; when you run a spec file, the spec supplies them and flags override. Flags are always honored.

Flag	Meaning
--data <file>	data file: .json object or .csv columns
--draws <n>	posterior draws (default 1000)
--warmup <n>	warmup iterations (default 1000)
--chains <n>	number of chains (default 4)
--adapt-delta <x>	NUTS target acceptance rate (default 0.8)
--max-depth <n>	NUTS tree depth limit from 1 to 20 (default 10)
--prior	draw from the prior instead of running MCMC (no warmup)
--algorithm <name>	sampler: NUTS, HMC, HMCDA, MH, ESS, SMC, PG, Slice, Gibbs, External, or Prior (default NUTS; Gibbs blocks, PG particles, and the Slice window are spec-only)
--thin <n>	keep every thin-th draw
--adtype <name>	AD backend for gradient samplers: forwarddiff, reversediff, or mooncake
--evaluation-mode <mode>	JuliaBUGS log-density evaluation: graph, generated, or marginalized (default: whatever the model file chose, with discrete latents marginalized for a gradient sampler when it chose nothing)
--monitor <name>	JuliaBUGS deterministic quantity to store with the parameters (repeatable; default: all of them)
--inits <file>	JSON object of starting values by variable name, used by every chain; entries holding a missing value are left out
--timeout <minutes>	give up on a fit after this long (default 30)
--parallel <mode>	chain execution: serial (default), threads, or distributed (Turing-only, one worker process per chain; incompatible with --stream-out)
--seed <n>	random seed (default: drawn fresh and recorded)
--backend <id>	backend, default detected from the model
--entry <name>	model entry function (default build_model)
-o, --out <file>	also export the samples file to this path
--report	open the finished run in the report web app (or set MCMC_REPORT_OPEN=1)
--store <dir>	run store directory (default: nearest .mcmc, or beside the model)
--julia-version <channel>	Julia version/channel to run, overriding the spec
--package <name=version>	pin a managed package version, repeatable (e.g. --package Turing=0.45)
--json	print results as JSON

A .stan model implies --backend stan, so you never need to pass it. --daemon, --julia-version, and --package are Julia-only and error on a Stan model, and --entry has no meaning for Stan.

Reuse and --refit

mcmc run records each run in a hidden .mcmc/ store keyed by the model, data, and settings. If nothing changed since the last run, it reuses the recorded result instead of refitting:

unchanged since run 20260626-050043-61ae20 (just now); reusing (--refit to force)

Pass --refit to fit again even when nothing changed. See The run store for how runs are recorded and referenced.

Streaming and the daemon

• --stream-out <file> streams sampled draws as NDJSON (one batch per line) to a file, or to stdout with -.
• --daemon fits through a persistent Julia worker (or set MCMC_DAEMON=1), which avoids paying Julia’s startup cost on every run. See Manage Julia.
• --verbose shows the full raw install/precompile output instead of a collapsed spinner.

mcmc fit: spec in, samples out

mcmc fit <spec> is the explicit inference step. It takes a spec file (TOML or JSON), runs MCMC, and writes a samples file. It does not diagnose or record a run; it is the composable primitive.

mcmc fit model.toml -o samples.json

Flag	Meaning
-o, --out <path>	samples output file, or a directory when --versions is used
--julia-version <channel>	Julia version/channel to run, overriding the spec
--versions <list>	run the spec across several Julia versions (comma-separated)
--package-versions <name=list>	run across versions of one managed package (e.g. Turing=0.44,0.45)
--keep-going	with a matrix, continue after a failure
--daemon	fit through a persistent Julia worker
--verbose	show raw install/precompile output
--json	print the result as JSON

The spec format, including [model], [sampler], and inline [data], is documented in the Spec file reference. The samples file it writes is documented in the Samples file reference.

Version matrices

--versions and --package-versions run the same spec across several Julia versions or several versions of one managed package, which is useful for reproducibility checks. For a Stan spec, --versions runs across installed CmdStan versions instead; --package-versions is Julia-only, as are --daemon and --julia-version. Point -o at a directory; each cell writes its own samples file there.

mcmc fit model.toml --versions 1.11,1.12 -o out/
mcmc fit model.toml --package-versions Turing=0.44,0.45 -o out/