You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
D. Bohdan 1a208578b7 docs(readme): reword note on date/time limitations 2 days ago
tests refactor: drop Python 2.7, Python 3.5 1 month ago
.gitattributes build(gitattributes): add .gitattributes 1 month ago
.gitignore Rewrite in Python 4 years ago
.travis.yml ci(travis): add Python 3.9 1 month ago
LICENSE docs: update copyright 7 months ago docs(readme): reword note on date/time limitations 2 days ago
appveyor.yml refactor: drop Python 2.7, Python 3.5 1 month ago
example.cbor test(cbor): add another test 7 months ago
example.json Rewrite in Python 4 years ago
example.msgpack feat(msgpack): implement MessagePack support 1 year ago
example.toml Use json.Number when decoding JSON. 6 years ago
example.yaml Rewrite in Python 4 years ago
poetry.lock feat(toml): support TOML 1.0.0-rc1 1 month ago
pyproject.toml refactor: drop Python 2.7, Python 3.5 1 month ago refactor(decode_toml): do not handle Null 1 month ago


Convert between CBOR, JSON, MessagePack, TOML, and YAML. When installed, provides the command line command remarshal as well as the short commands {cbor,json,msgpack,toml,yaml}2{cbor,json,msgpack,toml,yaml}. These commands can be used for format conversion, reformatting, and error detection.

Known limitations

  • CBOR, MessagePack, and YAML with binary fields can not be converted to JSON or TOML. Binary fields are converted between CBOR, MessagePack, and YAML.
  • TOML containing values of the Local Date-Time type can not be converted to CBOR. The Local Date type can only be converted to JSON and YAML. The Local Time type can not be converted to any other format. Offset Date-Time and its equivalents can be converted between CBOR, MessagePack, TOML, and YAML.
  • Date and time types are converted to JSON strings. They can’t be safely roundtripped through JSON.
  • A YAML timestamp with only a date becomes a TOML Local Date-Time for the midnight of that date.


You will need Python 3.6 or later. Earlier versions of Python 3 may work but are not supported.

You can install the latest release from PyPI using pip.

python3 -m pip install --user remarshal

Alternatively, clone the master branch to install the development version. Install Poetry then run

git clone
cd remarshal
poetry build
python3 -m pip install --user dist/remarshal-0.??.?-py2.py3-none-any.whl


usage: [-h] [-i input] [-o output]
                    [--if {cbor,json,msgpack,toml,yaml}]
                    [--of {cbor,json,msgpack,toml,yaml}]
                    [--indent-json n]
                    [--yaml-style {,',",|,>}]
                    [--wrap key] [--unwrap key]
                    [--preserve-key-order] [-v]
                    [input] [output]
usage: {cbor,json,msgpack,toml,yaml}2json [-h] [-i input] [-o output]
                                          [--indent-json n]
                                          [--wrap key] [--unwrap key]
                                          [--preserve-key-order] [-v]
                                          [input] [output]
usage: {cbor,json,msgpack,toml,yaml}2msgpack [-h] [-i input] [-o output]
                                             [--wrap key] [--unwrap key]
                                             [--preserve-key-order] [-v]
                                             [input] [output]
usage: {cbor,json,msgpack,toml,yaml}2toml [-h] [-i input] [-o output]
                                          [--wrap key] [--unwrap key]
                                          [--preserve-key-order] [-v]
                                          [input] [output]
usage: {cbor,json,msgpack,toml,yaml}2yaml [-h] [-i input] [-o output]
                                          [--yaml-style {,',",|,>}]
                                          [--wrap key] [--unwrap key]
                                          [--preserve-key-order] [-v]
                                          [input] [output]
usage: {cbor,json,msgpack,toml,yaml}2cbor [-h] [-i input] [-o output]
                                          [--wrap key] [--unwrap key]
                                          [--preserve-key-order] [-v]
                                          [input] [output]

All of the commands above exit with status 0 on success, 1 on operational failure, and 2 when they fail to parse the command line.

If no input argument input/ -i input is given or its value is - or a blank string the data to convert is read from the standard input. Similarly, with no output/-o output or an output argument that is - or a blank string the result of the conversion is written to the standard output.


The arguments --wrap and --unwrap are there to solve the problem of converting CBOR, JSON, MessagePack, and YAML data to TOML if the top-level element of that data is not of a dictionary type (i.e., not a map in CBOR and MessagePack, an object in JSON, or an associative array in YAML). Such data can not be represented as TOML directly; it must be wrapped in a dictionary first. Passing the flag --wrap someKey to remarshal or one of its short commands wraps the input data in a “wrapper” dictionary with one key, “someKey”, with the input data as its value. The flag --unwrap someKey does the opposite: if it is specified only the value stored under the key “someKey” in the top-level dictionary element of the input data is converted to the target format and output; all other data is ignored. If the top-level element is not a dictionary or does not have the key “someKey” then --unwrap someKey returns an error.

The following shell transcript demonstrates the problem and how --wrap and --unwrap solve it:

$ echo '[{"a":"b"},{"c":[1,2,3]}]' | ./ --if json --of toml
Error: cannot convert non-dictionary data to TOML; use "wrap" to wrap it in a dictionary

$ echo '[{"a":"b"},{"c":[1,2,3]}]' \
  | ./ --if json --of toml --wrap main
a = "b"

c = [1, 2, 3]

$ echo '[{"a":"b"},{"c":[1,2,3]}]' \
  | ./ --if json --wrap main - test.toml

$ ./ test.toml --of json

$ ./ test.toml --of json --unwrap main


$ ./ example.toml --of yaml
  - - gamma
    - delta
  - - 1
    - 2
  - alpha
  - omega
  connection_max: 5000
  enabled: true
  - 8001
  - 8001
  - 8002
  bio: 'GitHub Cofounder & CEO

    Likes tater tots and beer.'
  dob: 1979-05-27 07:32:00+00:00
  name: Tom Preston-Werner
  organization: GitHub
- name: Hammer
  sku: 738594937
- color: gray
  name: Nail
  sku: 284758393
    dc: eqdc10
    country: 中国
    dc: eqdc10
title: TOML Example

$ curl -s\?q\=Kiev,ua \
  | ./ --if json --of toml
base = "cmc stations"
cod = 200
dt = 1412532000
id = 703448
name = "Kiev"

all = 44

lat = 50.42999999999999972
lon = 30.51999999999999957

humidity = 66
pressure = 1026
temp = 283.49000000000000909
temp_max = 284.14999999999997726
temp_min = 283.14999999999997726

country = "UA"
id = 7358
message = 0.24370000000000000
sunrise = 1412481902
sunset = 1412522846
type = 1

description = "scattered clouds"
icon = "03n"
id = 802
main = "Clouds"

deg = 80
speed = 2


MIT. See the file LICENSE.

example.toml from example.json, example.msgpack, example.cbor, example.yml, tests/bin.msgpack, and tests/bin.yml are derived from it.