IDL compiler and RPC/distributed object framework for microservices

Latest on Hackage:0.3.3

This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow to host generated Haddocks.

GPL-3 licensed and maintained by Nirum team


The latest release on GitHub Docker automated build Build status on Linux and macOS (Travis CI) Build status on Windows (AppVeyor) Test coverage (codecov) Total lines of code Gitter

Nirum is an IDL compiler and RPC/distributed object framework for microservices, built on top of the modern Web server technologies such as RESTful HTTP and JSON.

You can find how the language looks like from source codes in the examples/ directory.

Note that its design is highly unstable and could be changed. Also the feature set is incomplete yet.


The Nirum compiler works on the most major platforms like Linux, macOS, and Windows. We provide the prebuilt executable binaries for these three platforms.

Released builds

You can download a executable binary for Linux (x86_64), macOS (x86_64), or Windows (x64 or x86) from the latest release note. You should give it appropriate permissions (e.g., +x) depending on your platform.

If you look for a previous release, see the list of all releases.

We provide official Docker images as well. You can check the list of released tags. Note that latest is for a nightly build which is unstable (see below).

Nightly builds

Since Nirum is still changing by leaps and bounds, you could want to try its bleeding edge. We provide nightly builds for this purpose.

Although we call it “nightly build,” technically it is not built every night, but done every merge commit.

Getting started

In order to compile a Nirum package (examples/) to a Python package:

$ mkdir out/  # directory to place generated Python files
$ nirum -t python -o out/ examples/

For more infomration, use --help option:

$ nirum --help
Nirum: The IDL compiler and RPC/distributed object framework

Usage: nirum [-v|--version] (-o|--output-dir DIR) (-t|--target TARGET) DIR
  Nirum compiler 0.3.3

Available options:
  -h,--help                Show this help text
  -v,--version             Show version
  -o,--output-dir DIR      Output directory
  -t,--target TARGET       Target language name. Available: docs, python
  DIR                      Package directory

There is a step-by-step tutorial as well.


If you already installed Haskell Stack, you can build the project in the same way to build other Haskell softwares:

$ stack build

You can run the test suite of Nirum:

$ stack test  # unit test for compiler
$ ./   # style lint

For details, please read the contribution guide.

Related projects & tools

See also the list of Nirum-related projects on GitHub. Have you kicked off a new project related to Nirum? Please add nirum topic to your project on GitHub!

Language runtimes

Editor supports


니름 (IPA: /niɾɯm/; nireum) is a sort of telepathy in the fictional world of The Bird That Drinks Tears (눈물을 마시는 새 Nunmureul masineun sae) by Lee Yeongdo (이영도).


Nirum changelog

Version 0.3.3

Released on March 15, 2018.

Et cetera

  • The official Docker images became to have CA certificates.

Version 0.3.2

Released on March 15, 2018.

Et cetera

  • Fixed a broken build of the official Docker images.

Version 0.3.1

Released on March 1, 2018.

Python target

  • Fixed record/union deserializers to ignore unknown fields in data payload. Deserializers had raised KeyError before. #232

Version 0.3.0

Released on February 18, 2018.


  • Package is now a new compilation unit of Nirum. Every Nirum package needs package.toml manifest file. [#83, #99]
  • Since a Nirum package can be compiled to more than one target languages, the nirum command became to have -t/--target required parameter. [#106, #111, #114]
  • Added -w/--watch mode. [#91, #104, #218]
  • Annotations became able to have multiple arguments and every parameter became necessary to having its name (keyword). [#178, #190, #197]
  • Service methods became able to omit their return types. [#179, #199 by Yang Chun Ung]
  • Added @error annotation to make a type to subclass an exception base class (e.g., Exception in Python) when it’s compiled to OO languages. [#38, #127]
  • Union tag docstrings in parentheses became allowed. [#153, #154]
  • Fixed a parser bug that a bare identifier (i.e., unquoted identifier) cannot start with a reserved keyword, e.g., types (type is reserved), enumeration (enum is reserved). [#184, #189]
  • Fixed a parser bug that import names had been disallowing to have a trailing comma or newlines. [#202]
  • Fixed the nirum command bug that it had always terminated with exit code 0 even when it errored. [#97, #108]

Docs target

  • A new target, docs is now available. To generate docs for a Nirum package, specify --target docs option to the nirum command. [#10, #113, #116, #125, #131, #152, #170, #223]

Python target

  • Now supports Python 2.7 besides Python 3.4 or later. [#50, #85, #93, #117, nirum-python #22]
  • Now requires nirum-python 0.6.0 or later. [#119, #141, #146]
  • From now on, in order to compile a Nirum package to Python, package.toml manifest need targets.python section and field. [#99]
  • Added targets.python.minimum_runtime option to specify the minimum version of nirum-python runtime library. [#118, #119]
  • Added targets.python.renames option to rename module names when they are compiled to a Python module. [#121]
  • More package metadata became configurable. [#100]
    • targets.python.description [#174 by Seunghun Lee]
    • targets.python.license [#180 by Seunghun Lee]
    • targets.python.keywords [#183 by Seunghun Lee]
  • Added new transport layer. [#149, nirum-python #79, nirum-python #92]
    • Generated constructors of service clients became to take a nirum.transport.Transport instance.
    • Followed renamed/moved import paths of the runtime classes (e.g., nirum.rpc.Service became to nirum.service.Service).
    • The way to avoid name collision between generated types and runtime classes is changed. The runtime library had provided alternative names like service_type for Service and generated imports had been like from nirum.rpc import service_type, but it’s now from nirum.service import Service as service_type.
  • Record/union tag fields of an optional type can be omitted when the constructor is called. [#70, #165 by Seunghun Lee]
  • Generated tag classes became qualified under its union class (e.g., Shape.Rectangle instead of Rectangle). Deprecated the old style and it is going to be obsolete in the near future. [#68, #193]
  • Generated service clients became qualified under its service class (e.g., FooService.Client instead of FooService_Client). Deprecated the old style and it is going to be obsolete in the near future. [#167, #222].
  • Generated serializers became independent from nirum-python runtime library. [#160, #201, #203, #204]
  • Deserializers became to show multiple error messages at a time. [#168, #224]
  • Generated Python classes became having __nirum_type__ metadata for RTTI. [nirum-python #34, #192]
  • Generated service classes became having __nirum_method_annotations__ metadata for processing annotations. [#194]
  • Docstrings in a Nirum schema became to generate corresponding Python docstrings. [#102, #128]
  • Sets, lists, and maps became compiled to immutable data structures so that thay are easily hashable. [nirum-python #49, #123]
  • Fixed a bug that implicit ancestor packages hadn’t been generated even if they have submodules. [#92, #105]
  • Fixed a bug that a generated Python code had raised NameError when a referring type is above than a referred type. [#138, nirum-python #88, #146]
  • Fixed a bug that a generated Python enum code had became broken when an enum type has a member named mro. [#185, #188]

Et cetera

  • The officialy distributed executable binaries for Linux became independent from glibc; instead statically linked to musl. #216
  • The Docker image now has nirum command in PATH. [#155]
  • The Docker image became based and built on Alpine Linux so that the image is now much lighter.

Version 0.2.0

Still unstable release. Released on September 26, 2016.


  • The boxed keyword was renamed to unboxed. [#65, #81]
  • Annotations became renewed and complete so that every type and module now can be annotated. [#40, #73]
  • Docstrings became merely a syntactic sugar of @docs annotation. [#53, #57]
  • Fixed a parser bug which had failed to parse spaces right before/after tag parentheses. [#69, #71]
  • Fixed a parser bug which had referred to a wrong line/column position on syntax error message when a trailing semicolon is missing. [#64]

Python target

  • Services became to have their own client implementation of a name with _Client postfix when they are compiled to Python. [#52]
  • Generated types became to have __hash__() method so that they are now hashable. [#75, #76]
  • Fixed a bug that a Python class generated from a parameterless tag had been broken. [#55, #66]

Et cetera

  • Introduced the official Docker image. The image repository is located to spoqa/nirum. [#48 by Minyoung Jeong]

Version 0.1.0

Initial and unstable release for a demo session at PyCon APAC 2016. Released on August 14, 2016.

comments powered byDisqus