Skip to main content

HTTP-based interface to Stan, a package for Bayesian inference.

Project description

Stan logo

pypi version travis-ci build status test coverage report

HTTP-based interface to Stan, a package for Bayesian inference.

An HTTP 1.1 interface to the Stan C++ package, httpstan is a shim that allows users to interact with the Stan C++ library using an HTTP API. The package is intended for use as a universal backend for frontends which know how to make HTTP requests. The primary audience for this package is developers.

In addition to providing all the functionality of the command-line interface to Stan (CmdStan) over HTTP 1.1, httpstan provides:

  • Automatic caching of compiled Stan models
  • Automatic caching of samples from Stan models
  • Parallel sampling

Documentation lives at

Important Disclaimer

httpstan is experimental software. This software is not intended for general use.

httpstan currently requires Python version 3.6 or higher. No older versions of Python will be supported.

httpstan only works on Linux and macOS. Windows support is planned.


httpstan is a shim allowing clients speaking HTTP to call functions in the Stan C++ package’s stan::services namespace. httpstan was originally developed as a “backend” for a Python interface to Stan, PyStan.


python3 -m pip install httpstan

Install from Source

A working copy of protoc is needed to build from source. One way to get this is to install grpcio-tools from PyPI with python3 -m pip install grpcio-tools.

make cython  # generate C++ code from Cython .pyx files
make protos  # generate Python modules for protocol buffer schemas
python3 install


After installing httpstan, running the module will begin listening on localhost, port 8080:

python3 -m httpstan

In a different terminal, make a POST request to http://localhost:8080/v1/models with Stan program code to compile the program:

curl -X POST -H "Content-Type: application/json" \
    -d '{"program_code":"parameters {real y;} model {y ~ normal(0,1);}"}' \

This request will return a model name along with all the compiler output:

{"name": "models/89c4e75a2c", "compiler_output": "..."}

(The model name depends on the platform and the version of Stan.)

To draw samples from this model using default settings, we first make the following request:

curl -X POST -H "Content-Type: application/json" \
    -d '{"function":"stan::services::sample::hmc_nuts_diag_e_adapt"}' \

This request instructs httpstan to draw samples from the normal distribution. The function name picks out a specific function in the Stan C++ library (see the Stan C++ documentation for details). This request will return immediately with a reference to the long-running fit operation:

{"done": false, "name": "operations/9f9d701294", "metadata": {"fit": {"name": "models/e1ca9f7ac7/fits/9f9d701294"}}}

Once the operation is completed, the “fit” can be retrieved. The name of the fit, models/e1ca9f7ac7/fits/9f9d701294, is included in the metadata field above. The fit is saved as sequence of Protocol Buffer messages. These messages are strung together using length-prefix encoding. To retrieve these messages, saving them in the file myfit.bin, make the following request:

curl http://localhost:8080/v1/models/e1ca9f7ac7/fits/9f9d701294 > myfit.bin

To read the messages you will need a library for reading the encoding that Protocol Buffer messages use. In this example we will read the first message in the stream using the Protocol Buffer compiler tool protoc. (On Debian-based Linux you can find this tool in the protobuf-compiler package.) The following command skips the message length (one byte) and then decodes the message (which is 48 bytes in length):

dd bs=1 skip=1 if=myfit.bin 2>/dev/null | head -c 48 | \
  protoc --decode stan.WriterMessage protos/callbacks_writer.proto

Running the command above decodes the first message in the stream. The decoded message should resemble the following:

topic: LOGGER
feature {
  string_list {
    value: "Gradient evaluation took 1.3e-05 seconds"


Contribution guidelines are described in CONTRIBUTE.rst.


ISC License.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for httpstan, version 0.7.1
Filename, size File type Python version Upload date Hashes
Filename, size httpstan-0.7.1-cp36-cp36m-macosx_10_6_intel.macosx_10_9_intel.macosx_10_9_x86_64.macosx_10_10_intel.macosx_10_10_x86_64.whl (31.5 MB) File type Wheel Python version cp36 Upload date Hashes View
Filename, size httpstan-0.7.1-cp36-cp36m-manylinux1_x86_64.whl (29.6 MB) File type Wheel Python version cp36 Upload date Hashes View
Filename, size httpstan-0.7.1-cp37-cp37m-macosx_10_6_intel.macosx_10_9_intel.macosx_10_9_x86_64.macosx_10_10_intel.macosx_10_10_x86_64.whl (31.5 MB) File type Wheel Python version cp37 Upload date Hashes View
Filename, size httpstan-0.7.1-cp37-cp37m-manylinux1_x86_64.whl (29.6 MB) File type Wheel Python version cp37 Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page