Ultra fast JSON encoder and decoder for Python
UltraJSON is an ultra fast JSON encoder and decoder written in pure C with bindings for Python 3.8+.
Install with pip:
python -m pip install ujson
May be used as a drop in replacement for most other JSON parsers for Python:
>>> import ujson
>>> ujson.dumps([{"key": "value"}, 81, True])
'[{"key":"value"},81,true]'
>>> ujson.loads("""[{"key": "value"}, 81, true]""")
[{'key': 'value'}, 81, True]
Used to enable special encoding of "unsafe" HTML characters into safer Unicode
sequences. Default is False
:
>>> ujson.dumps("<script>John&Doe", encode_html_chars=True)
'"\\u003cscript\\u003eJohn\\u0026Doe"'
Limits output to ASCII and escapes all extended characters above 127. Default is True
.
If your end format supports UTF-8, setting this option to false is highly recommended to
save space:
>>> ujson.dumps("åäö")
'"\\u00e5\\u00e4\\u00f6"'
>>> ujson.dumps("åäö", ensure_ascii=False)
'"åäö"'
Controls whether forward slashes (/
) are escaped. Default is True
:
>>> ujson.dumps("https://example.com")
'"https:\\/\\/example.com"'
>>> ujson.dumps("https://example.com", escape_forward_slashes=False)
'"https://example.com"'
Controls whether indentation ("pretty output") is enabled. Default is 0
(disabled):
>>> ujson.dumps({"foo": "bar"})
'{"foo":"bar"}'
>>> print(ujson.dumps({"foo": "bar"}, indent=4))
{
"foo":"bar"
}
UltraJSON calls/sec compared to other popular JSON parsers with performance gain specified below each.
Linux 5.15.0-1037-azure x86_64 #44-Ubuntu SMP Thu Apr 20 13:19:31 UTC 2023
ujson | orjson | simplejson | json | |
---|---|---|---|---|
Array with 256 doubles | ||||
encode | 18,282 | 79,569 | 5,681 | 5,935 |
decode | 28,765 | 93,283 | 13,844 | 13,367 |
Array with 256 UTF-8 strings | ||||
encode | 3,457 | 26,437 | 3,630 | 3,653 |
decode | 3,576 | 4,236 | 522 | 1,978 |
Array with 256 strings | ||||
encode | 44,769 | 125,920 | 21,401 | 23,565 |
decode | 28,518 | 75,043 | 41,496 | 42,221 |
Medium complex object | ||||
encode | 11,672 | 47,659 | 3,913 | 5,729 |
decode | 12,522 | 23,599 | 8,007 | 9,720 |
Array with 256 True values | ||||
encode | 110,444 | 425,919 | 81,428 | 84,347 |
decode | 203,430 | 318,193 | 146,867 | 156,249 |
Array with 256 dict{string, int} pairs | ||||
encode | 14,170 | 72,514 | 3,050 | 7,079 |
decode | 19,116 | 27,542 | 9,374 | 13,713 |
Dict with 256 arrays with 256 dict{string, int} pairs | ||||
encode | 55 | 282 | 11 | 26 |
decode | 48 | 53 | 27 | 34 |
Dict with 256 arrays with 256 dict{string, int} pairs, outputting sorted keys | ||||
encode | 42 | 8 | 27 | |
Complex object | ||||
encode | 462 | 397 | 444 | |
decode | 480 | 618 | 177 | 310 |
Above metrics are in call/sec, larger is better.
For those with particular needs, such as Linux distribution packagers, several build options are provided in the form of environment variables.
By default, debugging symbols are stripped on Linux platforms. Setting this
environment variable with a value of 1
or True
disables this behavior.
These two environment variables are typically used together, something like:
export UJSON_BUILD_DC_INCLUDES='/usr/include/double-conversion'
export UJSON_BUILD_DC_LIBS='-ldouble-conversion'
Users planning to link against an external shared library should be aware of the ABI-compatibility requirements this introduces when upgrading system libraries or copying compiled wheels to other machines.
One or more directories, delimited by os.pathsep
(same as the PATH
environment variable), in which to look for double-conversion
header files;
the default is to use the bundled copy.
Compiler flags needed to link the double-conversion
library; the default
is to use the bundled copy.