GitHub C++ Monthly Trending

ggml-org/llama.cpp

LLM inference in C/C++

llama.cpp

Manifesto / ggml / ops

LLM inference in C/C++

Recent API changes

Hot topics

Hugging Face cache migration: models downloaded with -hf are now stored in the standard Hugging Face cache directory, enabling sharing with other HF tools.
guide : using the new WebUI of llama.cpp
guide : running gpt-oss with llama.cpp
[FEEDBACK] Better packaging for llama.cpp to support downstream consumers 🤗
Support for the gpt-oss model with native MXFP4 format has been added | PR | Collaboration with NVIDIA | Comment
Multimodal support arrived in llama-server: #12898 | documentation
VS Code extension for FIM completions: https://github.com/ggml-org/llama.vscode
Vim/Neovim plugin for FIM completions: https://github.com/ggml-org/llama.vim
Hugging Face Inference Endpoints now support GGUF out of the box! https://github.com/ggml-org/llama.cpp/discussions/9669
Hugging Face GGUF editor: discussion | tool

Quick start

Getting started with llama.cpp is straightforward. Here are several ways to install it on your machine:

Install llama.cpp using brew, nix or winget
Run with Docker - see our Docker documentation
Download pre-built binaries from the releases page
Build from source by cloning this repository - check out our build guide

Once installed, you'll need a model to work with. Head to the Obtaining and quantizing models section to learn more.

Example command:

# Use a local model file
llama-cli -m my_model.gguf

# Or download and run a model directly from Hugging Face
llama-cli -hf ggml-org/gemma-3-1b-it-GGUF

# Launch OpenAI-compatible API server
llama-server -hf ggml-org/gemma-3-1b-it-GGUF

Description

The main goal of llama.cpp is to enable LLM inference with minimal setup and state-of-the-art performance on a wide range of hardware - locally and in the cloud.

Plain C/C++ implementation without any dependencies
Apple silicon is a first-class citizen - optimized via ARM NEON, Accelerate and Metal frameworks
AVX, AVX2, AVX512 and AMX support for x86 architectures
RVV, ZVFH, ZFH, ZICBOP and ZIHINTPAUSE support for RISC-V architectures
1.5-bit, 2-bit, 3-bit, 4-bit, 5-bit, 6-bit, and 8-bit integer quantization for faster inference and reduced memory use
Custom CUDA kernels for running LLMs on NVIDIA GPUs (support for AMD GPUs via HIP and Moore Threads GPUs via MUSA)
Vulkan and SYCL backend support
CPU+GPU hybrid inference to partially accelerate models larger than the total VRAM capacity

The llama.cpp project is the main playground for developing new features for the ggml library.

Models

Typically finetunes of the base models below are supported as well.

Instructions for adding support for new models: HOWTO-add-model.md

Text-only

Multimodal

Bindings

Python: ddh0/easy-llama
Python: abetlen/llama-cpp-python
Go: go-skynet/go-llama.cpp
Node.js: withcatai/node-llama-cpp
JS/TS (llama.cpp server client): lgrammel/modelfusion
JS/TS (Programmable Prompt Engine CLI): offline-ai/cli
JavaScript/Wasm (works in browser): tangledgroup/llama-cpp-wasm
Typescript/Wasm (nicer API, available on npm): ngxson/wllama
Ruby: yoshoku/llama_cpp.rb
Ruby: docusealco/rllama
Rust (more features): edgenai/llama_cpp-rs
Rust (nicer API): mdrokz/rust-llama.cpp
Rust (more direct bindings): utilityai/llama-cpp-rs
Rust (automated build from crates.io): ShelbyJenkins/llm_client
C#/.NET: SciSharp/LLamaSharp
C#/VB.NET (more features - community license): LM-Kit.NET
Scala 3: donderom/llm4s
Clojure: phronmophobic/llama.clj
React Native: mybigday/llama.rn
Java: kherud/java-llama.cpp
Java: QuasarByte/llama-cpp-jna
Zig: deins/llama.cpp.zig
Flutter/Dart: netdur/llama_cpp_dart
Flutter: xuegao-tzx/Fllama
PHP (API bindings and features built on top of llama.cpp): distantmagic/resonance (more info)
Guile Scheme: guile_llama_cpp
Swift srgtuszy/llama-cpp-swift
Swift ShenghaiWang/SwiftLlama
Delphi Embarcadero/llama-cpp-delphi
Go (no CGo needed): hybridgroup/yzma
Android: llama.android

UIs

(to have a project listed here, it should clearly state that it depends on llama.cpp)

AI Sublime Text plugin (MIT)
BonzAI App (proprietary)
cztomsik/ava (MIT)
Dot (GPL)
eva (MIT)
iohub/collama (Apache-2.0)
janhq/jan (AGPL)
johnbean393/Sidekick (MIT)
KanTV (Apache-2.0)
KodiBot (GPL)
llama.vim (MIT)
LARS (AGPL)
Llama Assistant (GPL)
LlamaLib (Apache-2.0)
LLMFarm (MIT)
LLMUnity (MIT)
LMStudio (proprietary)
LocalAI (MIT)
LostRuins/koboldcpp (AGPL)
MindMac (proprietary)
MindWorkAI/AI-Studio (FSL-1.1-MIT)
Mobile-Artificial-Intelligence/maid (MIT)
Mozilla-Ocho/llamafile (Apache-2.0)
nat/openplayground (MIT)
nomic-ai/gpt4all (MIT)
ollama/ollama (MIT)
oobabooga/text-generation-webui (AGPL)
PocketPal AI (MIT)
psugihara/FreeChat (MIT)
ptsochantaris/emeltal (MIT)
pythops/tenere (AGPL)
ramalama (MIT)
semperai/amica (MIT)
withcatai/catai (MIT)
Autopen (GPL)

Tools

akx/ggify – download PyTorch models from Hugging Face Hub and convert them to GGML
akx/ollama-dl – download models from the Ollama library to be used directly with llama.cpp
crashr/gppm – launch llama.cpp instances utilizing NVIDIA Tesla P40 or P100 GPUs with reduced idle power consumption
gpustack/gguf-parser - review/check the GGUF file and estimate the memory usage
Styled Lines (proprietary licensed, async wrapper of inference part for game development in Unity3d with pre-built Mobile and Web platform wrappers and a model example)
unslothai/unsloth – 🦥 exports/saves fine-tuned and trained models to GGUF (Apache-2.0)

Infrastructure

Paddler - Open-source LLMOps platform for hosting and scaling AI in your own infrastructure
GPUStack - Manage GPU clusters for running LLMs
llama_cpp_canister - llama.cpp as a smart contract on the Internet Computer, using WebAssembly
llama-swap - transparent proxy that adds automatic model switching with llama-server
Kalavai - Crowdsource end to end LLM deployment at any scale
llmaz - ☸️ Easy, advanced inference platform for large language models on Kubernetes.
LLMKube - Kubernetes operator for llama.cpp with multi-GPU and Apple Silicon Metal support"

Games

Lucy's Labyrinth - A simple maze game where agents controlled by an AI model will try to trick you.

Supported backends

Backend	Target devices
Metal	Apple Silicon
BLAS	All
BLIS	All
SYCL	Intel and Nvidia GPU
OpenVINO [In Progress]	Intel CPUs, GPUs, and NPUs
MUSA	Moore Threads GPU
CUDA	Nvidia GPU
HIP	AMD GPU
ZenDNN	AMD CPU
Vulkan	GPU
CANN	Ascend NPU
OpenCL	Adreno GPU
IBM zDNN	IBM Z & LinuxONE
WebGPU [In Progress]	All
RPC	All
Hexagon [In Progress]	Snapdragon
VirtGPU	VirtGPU APIR

Obtaining and quantizing models

The Hugging Face platform hosts a number of LLMs compatible with llama.cpp:

You can either manually download the GGUF file or directly use any llama.cpp-compatible models from Hugging Face or other model hosting sites, by using this CLI argument: -hf <user>/<model>[:quant]. For example:

llama-cli -hf ggml-org/gemma-3-1b-it-GGUF

By default, the CLI would download from Hugging Face, you can switch to other options with the environment variable MODEL_ENDPOINT. The MODEL_ENDPOINT must point to a Hugging Face compatible API endpoint.

After downloading a model, use the CLI tools to run it locally - see below.

llama.cpp requires the model to be stored in the GGUF file format. Models in other data formats can be converted to GGUF using the convert_*.py Python scripts in this repo.

The Hugging Face platform provides a variety of online tools for converting, quantizing and hosting models with llama.cpp:

Use the GGUF-my-repo space to convert to GGUF format and quantize model weights to smaller sizes
Use the GGUF-my-LoRA space to convert LoRA adapters to GGUF format (more info: https://github.com/ggml-org/llama.cpp/discussions/10123)
Use the GGUF-editor space to edit GGUF meta data in the browser (more info: https://github.com/ggml-org/llama.cpp/discussions/9268)
Use the Inference Endpoints to directly host llama.cpp in the cloud (more info: https://github.com/ggml-org/llama.cpp/discussions/9669)

To learn more about model quantization, read this documentation

`llama-cli`

A CLI tool for accessing and experimenting with most of `llama.cpp`'s functionality.

Run in conversation mode

Models with a built-in chat template will automatically activate conversation mode. If this doesn't occur, you can manually enable it by adding -cnv and specifying a suitable chat template with --chat-template NAME

llama-cli -m model.gguf

# > hi, who are you?
# Hi there! I'm your helpful assistant! I'm an AI-powered chatbot designed to assist and provide information to users like you. I'm here to help answer your questions, provide guidance, and offer support on a wide range of topics. I'm a friendly and knowledgeable AI, and I'm always happy to help with anything you need. What's on your mind, and how can I assist you today?
#
# > what is 1+1?
# Easy peasy! The answer to 1+1 is... 2!

Run in conversation mode with custom chat template

# use the "chatml" template (use -h to see the list of supported templates)
llama-cli -m model.gguf -cnv --chat-template chatml

# use a custom template
llama-cli -m model.gguf -cnv --in-prefix 'User: ' --reverse-prompt 'User:'

Constrain the output with a custom grammar
```
llama-cli -m model.gguf -n 256 --grammar-file grammars/json.gbnf -p 'Request: schedule a call at 8pm; Command:'

# {"appointmentTime": "8pm", "appointmentDetails": "schedule a a call"}
```
The grammars/ folder contains a handful of sample grammars. To write your own, check out the GBNF Guide.

For authoring more complex JSON grammars, check out https://grammar.intrinsiclabs.ai/

`llama-server`

A lightweight, OpenAI API compatible, HTTP server for serving LLMs.

Start a local HTTP server with default configuration on port 8080

llama-server -m model.gguf --port 8080

# Basic web UI can be accessed via browser: http://localhost:8080
# Chat completion endpoint: http://localhost:8080/v1/chat/completions

Support multiple-users and parallel decoding

# up to 4 concurrent requests, each with 4096 max context
llama-server -m model.gguf -c 16384 -np 4

Enable speculative decoding

# the draft.gguf model should be a small variant of the target model.gguf
llama-server -m model.gguf -md draft.gguf

Serve an embedding model

# use the /embedding endpoint
llama-server -m model.gguf --embedding --pooling cls -ub 8192

Serve a reranking model

# use the /reranking endpoint
llama-server -m model.gguf --reranking

Constrain all outputs with a grammar

# custom grammar
llama-server -m model.gguf --grammar-file grammar.gbnf

# JSON
llama-server -m model.gguf --grammar-file grammars/json.gbnf

`llama-perplexity`

A tool for measuring the perplexity ^[1] (and other quality metrics) of a model over a given text.

Measure the perplexity over a text file

llama-perplexity -m model.gguf -f file.txt

# [1]15.2701,[2]5.4007,[3]5.3073,[4]6.2965,[5]5.8940,[6]5.6096,[7]5.7942,[8]4.9297, ...
# Final estimate: PPL = 5.4007 +/- 0.67339

Measure KL divergence
```
# TODO
```

`llama-bench`

Benchmark the performance of the inference for various parameters.

Run default benchmark

llama-bench -m model.gguf

# Output:
# | model               |       size |     params | backend    | threads |          test |                  t/s |
# | ------------------- | ---------: | ---------: | ---------- | ------: | ------------: | -------------------: |
# | qwen2 1.5B Q4_0     | 885.97 MiB |     1.54 B | Metal,BLAS |      16 |         pp512 |      5765.41 ± 20.55 |
# | qwen2 1.5B Q4_0     | 885.97 MiB |     1.54 B | Metal,BLAS |      16 |         tg128 |        197.71 ± 0.81 |
#
# build: 3e0ba0e60 (4229)

`llama-simple`

A minimal example for implementing apps with `llama.cpp`. Useful for developers.

Basic text completion

llama-simple -m model.gguf

# Hello my name is Kaitlyn and I am a 16 year old girl. I am a junior in high school and I am currently taking a class called "The Art of

Contributing

Contributors can open PRs
Collaborators will be invited based on contributions
Maintainers can push to branches in the llama.cpp repo and merge PRs into the master branch
Any help with managing issues, PRs and projects is very appreciated!
See good first issues for tasks suitable for first contributions
Read the CONTRIBUTING.md for more information
Make sure to read this: Inference at the edge
A bit of backstory for those who are interested: Changelog podcast

XCFramework

The XCFramework is a precompiled version of the library for iOS, visionOS, tvOS, and macOS. It can be used in Swift projects without the need to compile the library from source. For example:

// swift-tools-version: 5.10
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "MyLlamaPackage",
    targets: [
        .executableTarget(
            name: "MyLlamaPackage",
            dependencies: [
                "LlamaFramework"
            ]),
        .binaryTarget(
            name: "LlamaFramework",
            url: "https://github.com/ggml-org/llama.cpp/releases/download/b5046/llama-b5046-xcframework.zip",
            checksum: "c19be78b5f00d8d29a25da41042cb7afa094cbf6280a225abe614b03b20029ab"
        )
    ]
)

The above example is using an intermediate build b5046 of the library. This can be modified to use a different version by changing the URL and checksum.

Completions

Command-line completion is available for some environments.

Bash Completion

$ build/bin/llama-cli --completion-bash > ~/.llama-completion.bash
$ source ~/.llama-completion.bash

Optionally this can be added to your .bashrc or .bash_profile to load it automatically. For example:

$ echo "source ~/.llama-completion.bash" >> ~/.bashrc

Dependencies

yhirose/cpp-httplib - Single-header HTTP server, used by llama-server - MIT license
stb-image - Single-header image format decoder, used by multimodal subsystem - Public domain
nlohmann/json - Single-header JSON library, used by various tools/examples - MIT License
miniaudio.h - Single-header audio format decoder, used by multimodal subsystem - Public domain
subprocess.h - Single-header process launching solution for C and C++ - Public domain

https://huggingface.co/docs/transformers/perplexity ↩︎

imputnet/helium

Private, fast, and honest web browser

Helium

The Chromium-based web browser made for people, with love.
Privacy-first with unbiased ad-blocking. No bloat and no noise.

helium.computer

Downloads

Note

Helium is currently in beta, so unexpected issues may occur. Please report them if they haven't already been reported.

The easiest way to download Helium is helium.computer. It'll pick a compatible binary for your platform automatically.

The same releases can also be downloaded from source on GitHub:

Helium repos

All Helium packaging, tooling, services, and components are open source and published on GitHub.

Platform packaging and tooling

Web services and Helium components

Development

macOS is our primary development platform, so it's the recommended development environment for community contributions.

Linux packaging includes a similar development script, so the same guide can be applied there too.

> See development docs in macOS repo

Contributing

Before contributing to Helium, please read the guidelines in CONTRIBUTING.md.

Credits

The Chromium project

The Chromium Project is at the core of Helium, making it possible in the first place.

ungoogled-chromium

This repo is based on ungoogled-chromium, but heavily modified for Helium. Special thanks to everyone behind ungoogled-chromium, they made working with Chromium way easier.

Other Chromium browsers

Helium includes some patches from other open source Chromium browsers:

All patches are sorted by vendor in the patches directory of this repo.

License

All code, patches, modified portions of imported code or patches, and any other content that is unique to Helium and not imported from other repositories is licensed under GPL-3.0. See LICENSE.

Any content imported from other projects retains its original license (for example, any original unmodified code imported from ungoogled-chromium remains licensed under their BSD 3-Clause license).

ikawrakow/ik_llama.cpp

llama.cpp fork with additional SOTA quants and improved performance

ik_llama.cpp: llama.cpp fork with better CPU performance

TL;DR

This repository is a fork of llama.cpp with better CPU and hybrid GPU/CPU performance, new SOTA quantization types, first-class Bitnet support, better DeepSeek performance via MLA, FlashMLA, fused MoE operations and tensor overrides for hybrid GPU/CPU inference, row-interleaved quant packing, etc.

Important

If you are running hybrid CPU/GPU inference for MoE models with all or some experts left on the CPU, do not use -rtr unless you know what you are doing. The -rtr option causes all tensors left in RAM to be repacked to row-interleaved format while loading the model. As not all quantization types have a CUDA implementation, this will result in matrix multiplications with these tensors to be always done on the CPU, even when it would have been much better to offload the computation to the GPU, typically resulting in much lower prompt processing speed. Most notably, k-quants (K2_K, Q3_K, Q4_K, Q5_K, Q6_K) do not have CUDA row-interleaved implementation.

Note

The only fully functional and performant compute backends are CPU (AVX2 or better, ARM_NEON or better) and CUDA (Turing or newer). Please do not enter issues related to ROCm, Vulkan, Metal, old Nvidia GPUs, AVX CPUs, etc. They will not get resolved unless you roll up your sleeves and help bring your favorite backend up to speed. With the current regular contributors this project simply does not have the bandwidth to work on all backends available in llama.cpp.

Important

Do not use quantized models from Unsloth that have _XL in their name. These are likely to not work with ik_llama.cpp.

The above has caused some stir, so to clarify: the Unsloth _XL models that are likely to not work are those that contain f16 tensors (which is never a good idea in the first place). All others are fine.

Note

Some users have reported issues with graph parallel (a.k.a. split mode graph) and partial GPU offload (using --cpu-moe or --n-cpu-moe or tensor overrides). If you are using/want to use split mode graph and observe gibberish/incoherent responses, try adding -cuda graphs=0 to your command line.

Quickstart

Prerequisites

git clone https://github.com/ikawrakow/ik_llama.cpp

cd ik_llama.cpp

On Debian/Ubuntu Linux, install the required packages (if using another Linux distro, you need to find the corresponding packages and adapt):

apt-get update && apt-get install build-essential git libcurl4-openssl-dev curl libgomp1 cmake

Build for CPU

cmake -B build -DGGML_NATIVE=ON

cmake --build build --config Release -j$(nproc)

For AVX-512-capable CPUs (AMD Zen4 / Intel Sapphire Rapids+), see docs/build.md section "CPU build flags for AVX-512" for the additional flags that activate the IQK quantized GEMM kernels (the HAVE_FANCY_SIMD path). Without those flags, a vanilla Release build silently falls back to the AVX2 path on this hardware.

Build for GPU

Install Nvidia Drivers and CUDA Toolkit.

cmake -B build -DGGML_NATIVE=ON -DGGML_CUDA=ON

cmake --build build --config Release -j$(nproc)

Step-by-step instructions for a case of a successful Windows build

https://github.com/ikawrakow/ik_llama.cpp/blob/main/docs/build.md

Run

Download .gguf model files (e.g. bartowski/Qwen_Qwen3-0.6B-IQ4_NL.gguf) to your favorite directory (e.g. /my_local_files/gguf).

Start the server with one of the commands (CPU or GPU):

./build/bin/llama-server --model /my_local_files/gguf/Qwen_Qwen3-0.6B-IQ4_NL.gguf --ctx-size 4096

./build/bin/llama-server --model /my_local_files/gguf/Qwen_Qwen3-0.6B-IQ4_NL.gguf --ctx-size 4096 -ngl 999

That's all! Open http://127.0.0.1:8080 in Browser start chatting.

Step by step guide for ik_llama.cpp in podman/docker container including llama-swap

Common parameters and options

Latest News

Model Support

LlaMA-3-Nemotron PR 377, Qwen3 PR 355, GLM-4 PR 344, Command-A PR 341, bitnet-b1.58-2B-4T PR 337, LLaMA-4 PR 321, Gemma3 PR 276, DeepSeek-V3 PR 176, Kimi-2 PR 609, dots.llm1 PR 573, Hunyuan PR 565, GLM-4.5 PR 668 (4.5/4.6/4.7/AIR), Ernie 4.5 MOE and 0.3B PR 759, grok-2 PR 782, Ling/Ring (Bailing-MoE2) PR 833, Qwen3-VL PR 883, SmolLM3 PR 934, GigaChat3 PR 995, ministral3 PR 1030, Mimo-V2-Flash PR 1096, GLM-4.7-Flash PR 1168, Seed-OSS PR 1218, Step-3.5-Flash PR 1231, GLM-5 PR 1268, Qwen3-Next PR 1266, Qwen3.5-MoE PR 1288 and dense Qwen-3.5 1326, Mistral 4 PR 1450, Bonsai 1-bit PR 1570, Gemma4 PR 1581, Mimo-2.5 PR 1723

Quantization

Quantization additions

Trellis quants (`IQ1_KT`, `IQ2_KT`, `IQ3_KT`, `IQ4_KT`)

Information and the original CUDA implementation in PR 113. Additional implementations: Metal PR 475, Neon PR 471, CPU PR 441. IQ1_KT was added more recently in PR 616. Note: these are base on a novel, integer-base trellis, which allows to achieve reasonable CPU performance, see PR 529 and PRs quoted there for details.

IQK quants

Information can be found in Discussion 8.

Initial implementations (Zen4, AVX2, NEON): IQ5_KS_R4 PR 426, IQ5_KS PR 422, IQ4_KS_R4 PR 150, IQ5_K_R4 PR 149, IQ2_K_R4 PR 146, IQ3_K_R4 PR 145, IQ4_K_R4 PR 138, IQ4_KSS PR 89, IQ2_KS PR 85, IQ4_KS PR 83, IQ6_K PR 14, IQ2_K, IQ3_K and IQ5_K PR 7, IQ4_K PR 6

Cuda implementations: IQ4_KS_R4 and IQ5_KS_R4 PR 493, IQ1_S_R4 PR 492, IQ1_M_R4 PR 494. IQ4_KS_R4 and IQ5_KS_R4 PR 462, IQ2_K_R4, IQ3_K_R4, IQ4_K_R4, IQ5_K_R4 PR 461, IQ4_K, IQ5_K, IQ6_K PR 417, IQ2_KS, IQ2_K, IQ3_K PR 418

IQ2_KL is a more recent addition in PR 602

Hadamard transforms for K-cache

CPU PR 1033 and CUDA PR 1034

Hadamard transforms for V-cache

PR 1527

MXFP4 as used in gpt-oss models

Implemented for Zen4, AVX2, ARM_NEON, Metal, CUDA PR 682

Quantization improvements

IQ1_M PR 327, IQ2_XS PR 312, Q2_K, Q4_K, Q5_K, Q4_1, Q5_1 PR 302, Q4_0, Q5_0, Q6_0, Q3_K, Q6_K, IQ4_XS, IQ4_NL PR 295
Low perplexity Q4_0 KV cache PR 1547 PR 1556

Quantization performance improvements

Much faster CPU prompt processing for all non-interleaved quants. Initial idea in PR 515 and PR 531, with many follow up PRs to apply to all quantization types for the 3 supported CPU platforms.
All quantization types now have quantized matrix multiplication CUDA kernels, see PR 557 and several others
Faster CPU prompt processing for Trellis quants and MoE models. PR 488
Trellis quants: faster CPU prompt processing PR 482.
Minor (~2%) iq2_ks TG performance improvement on CUDA PR 468
Faster IQ3_KT and IQ4_KT PR 453
Zen4: Faster PP for IQ2_KS, IQ4_KS, IQ5_KS PR 428
Fast GEMM/GEMV for IQ1_S PR 212
AVX-VNNI optimizations PR 1446 PR 1455 PR 1467 PR 1474 PR 1482

Features

New split mode "graph" for multi GPU setups PR 1022
Fused delta-net for Qwen3-Next and Qwen3.5-MoE PR 1315 PR 1333 PR 1362 PR 1373
Hadamard transforms for K-cache and V-cache PR 1033 PR 1034 PR 1527
Auto-fit offloaded tensors to available VRAM (MoE and dense models) PR 1501 PR 1504
Checkpoints for recurrent models PR 1310 PR 1398
MTP decoding support for popular models like GLM-4.x MoE 1270, Qwen 3.5/3.6 1698 1745, Gemma 4 1744
Self speculative decoding, ngram PR 1261, suffix PR 1646
String ban function for all completions PR 1185 PR 1243
Expiring Logit Bias PR 1731
OpenAI /v1/responses API endpoint PR 1184
Function call support PR 628
jinja template support PR 677
Webui: New Features for Conversations, Settings, and Chat Messages PR 618
Dynamic control vector management endpoints PR 1223
Legacy quants conversion schemes in convert_hf_to_gguf.py PR 449, Q6_0 in PR 483
Adaptive-P Sampler PR 1100 implemented as designed by it's author; supported on Webui
Multi-modal Vision support in llama-mtmd-cli PR 798 and in llama-server PR 901
mikupad as an alternative WebUI PR 558
June 8 2025: Webui updated (legacy still available when --path ./examples/server/public_legacy is passed) PR 481
June 8 2025: RPC improvements PR 480
June 7 2025: Add an endpoint that lists all the saved prompt caches to server PR 502
June 6 2025: Make prompt cache saving and restoring MLA aware PR 497
June 3 2025: Added samplers, XTC PR 486, top-n σ PR 489.
May 22 2025: Refactor iqk_mul_mat.cpp which speeds up compilation time significantly. PR 435
May 17 2025: Option to enable or disable the CPU FA kernels PR 429.
May 12 2025: User can now control if/which operations with tensors held in RAM are offloaded to the GPU. See PR 405
May 12 2025: Compatibility issues with mainline llama.cpp GGUFs for DeepSeek models with MLA enabled were resolved in PR 394. The lower prompt processing performance resulting from using llama.cpp-style MLA GGUFs was recovered in PR 409.
April 21 2025: ik_llama.cpp builds and runs successfully on Android (using termux), see PR 336
March 1 2025: Smart Expert Reduction for faster DeepSeek inference PR 239
Feb 25 2025: Tensor overrides for better control where model weights are stored (GPU or CPU) PR 232
Feb 23 2025: sweep-bench - better performance benchmarking PR 225
Feb 19 2025: Q8_KV - new type for 8-bit KV-cache quantization PR 208
March 7 2025: Custom quantization mixes using regular expressions PR 244

Performance improvements

Better GPU offload strategy for MoE models when using hybrid HPU/CPU inference, see PR 520
Much faster rng sampling PR 1187
May 13 2025: Better CPU FA performance for DeepSeek-Lite. PR 410
May 11 2025: Slightly faster flash attention for DeepSeek models on CUDA, along with extending compatibility to Touring or newer GPUs. PR 408
May 4 2025: Significant token generation performance improvement on CUDA with Flash Attention for GQA models. For details and benchmarks. PR 370
April 17 2025: Better CPU Flash Attention token generation performance. PR 332
April 3 2025: Much faster MoE implementation on Metal. PR 307
March 25 2025: Better MoE performance on CUDA PR 283
March 23 2025: Better batched processing speed for DeepSeek models PR 282
March 18 2025: Reduce compute buffer size PR 237
March 10 2025: Better TG performance for MoE models on CUDA PR 248
Feb 23 2025: Fused FFN ops for faster MoE inference PR 229

Flash-MLA

May 7 2025: 🚀 FlashMLA-3 for DeepSeek models on CUDA. PR 386. Caveat: Ampere or newer Nvidia GPU required
March 21 2025: 🚀 FlashMLA-3: fastest CPU-only inference for DeepSeek models PR 273
March 17 2025: 🚀 FlashMLA-2 performance improvements PR 253
March 12 2025: Allow Q8_0 KV cache with FlashMLA-2 on CUDA PR 265
March 9 2025: 🚀 FlashMLA on CUDA PR 247
March 8 2025: 🚀 Faster FlashMLA CPU implementation PR 243
March 3 2025: 🚀 Introducing FlashMLA - MLA with Flash Attention PR 240
Feb 27 2025: MLA without transposed cache PR 235
Feb 13 2025: Allow Q8_0 quantized cache with MLA PR 206
Feb 11 2025: 🚀 Flash Attention support for DeepSeek models PR 200
Feb 9 2025: 🚀 MLA for DeepSeek models PR 188

Fixes

Fix bug in MMVQ kernel PR 446
Fix AVX2 implementation of IQ4_K, IQ4_KS, IQ5_K, IQ6_K PR 427
Fix standard attention on the CPU PR 421
Fix imatrix calculation for MLA models PR 411
Fix new CUDA FA on Touring PR 413
Fix SER. CPU: PR 415 CUDA: PR 416

Resources

There is no single point of reference describing all new ik_llama.cpp features. Pull requests often contain detailed information, so browsing the PRs is often the best way to learn about new features and how to use them. In addition

The Wiki page has performance comparisons to mainline llama.cpp
This guide is a good place to start if you came here because of DeepSeek models
This discussion is about running DeepSeek-V3/R1 on a 16 x 3090 setup
This discussion describes the new quantization types available in ik_llama.cpp

Testing

Function Calls Tests

To run the function calls test suite:

cd build
cmake --build . --target test-function-calls
./bin/test-function-calls

The test suite covers parser functionality, streaming, error handling, content cleaning, and server integration. All tests should pass to ensure production readiness.

Contributing

Contributions in form of pull requests, issue submissions (bug reports, feature requests), or general discussions, are welcome.

License

subprocess.h - Single-header process launching solution for C and C++ - Public domain
server
GBNF grammars

Development documentation

Seminal papers and background on the models

LLaMA:
- Introducing LLaMA: A foundational, 65-billion-parameter large language model
- LLaMA: Open and Efficient Foundation Language Models
GPT-3
- Language Models are Few-Shot Learners
GPT-3.5 / InstructGPT / ChatGPT:
- Aligning language models to follow instructions
- Training language models to follow instructions with human feedback

Completions

Command-line completion is available for some environments.

Bash Completion

$ build/bin/llama-cli --completion-bash > ~/.llama-completion.bash
$ source ~/.llama-completion.bash

Optionally this can be added to your .bashrc or .bash_profile to load it automatically. For example:

$ echo "source ~/.llama-completion.bash" >> ~/.bashrc

Dependencies

yhirose/cpp-httplib - Single-header HTTP server, used by llama-server - MIT license
stb-image - Single-header image format decoder, used by multimodal subsystem - Public domain
nlohmann/json - Single-header JSON library, used by various tools/examples - MIT License
miniaudio.h - Single-header audio format decoder, used by multimodal subsystem - Public domain
subprocess.h - Single-header process launching solution for C and C++ - Public domain

ValveSoftware/Proton

Compatibility tool for Steam Play based on Wine and additional components

Introduction

Proton is a tool for use with the Steam client which allows games which are exclusive to Windows to run on the Linux operating system. It uses Wine to facilitate this.

Most users should use Proton provided by the Steam Client itself. See this Steam Community post for more details.

The source code is provided to enable advanced users the ability to alter Proton. For example, some users may wish to use a different version of Wine with a particular title.

The changelog is available on our wiki.

Obtaining Proton sources

Acquire Proton's source by cloning https://github.com/ValveSoftware/Proton and checking out the branch you desire.

You can clone the latest Proton to your system with this command:

git clone --recurse-submodules https://github.com/ValveSoftware/Proton.git proton

Be sure to update submodules when switching between branches:

git checkout experimental_6.3
git submodule update --init --recursive

If you want to change any subcomponent, now is the time to do so. For example, if you wish to make changes to Wine, you would apply them to the wine/ directory.

Building Proton

Most of Proton builds inside the Proton SDK container with very few dependencies on the host side.

Preparing the build environment

You need either a Docker or a Podman setup which Proton's build system uses internally. You should never need to use either container engine manually unless working on those parts of build system directly.

We highly recommend the rootless Podman setup. Please refer to your distribution's documentation for setup instructions (e.g. Arch Podman / Docker, Debian Podman / Docker).

The Easy Way

We provide a top-level Makefile which will execute most of the build commands for you.

After checking out the repository and updating its submodules, assuming that you have a working Docker or Podman setup, you can build and install Proton with a simple:

make install

If your build system is missing dependencies, it will fail quickly with a clear error message.

After the build finishes, you may need to restart the Steam client to see the new Proton tool. The tool's name in the Steam client will be based on the currently checked out branch of Proton. You can override this name using the build_name variable.

See make help for other build targets and options.

Manual building

Configuring the build

mkdir ../build && cd ../build
../proton/configure.sh --enable-ccache --build-name=my_build

Running configure.sh will create a Makefile allowing you to build Proton. The scripts checks if containers are functional and prompt you if any host-side dependencies are missing. You should run the command from a directory created specifically for your build.

The configuration script tries to discover a working Docker or Podman setup to use, but you can force a compatible engine with --container-engine=<executable_name>.

You can enable ccache with --enable-cache flag. This will mount your $CCACHE_DIR or $HOME/.ccache inside the container.

--proton-sdk-image=registry.gitlab.steamos.cloud/proton/soldier/sdk:<version> can be used to build with a custom version of the Proton SDK images.

Check --help for other configuration options.

NOTE: If SELinux is in use, the Proton build container may fail to access your user's files. This is caused by SELinux's filesystem labels. You may pass the --relabel-volumes switch to configure to cause the container engine to relabel its bind-mounts and allow access to those files from within the container. This can be dangerous when used with system directories. Proceed with caution and refer your container engine's manual.

Building

make

Important make targets:

make install - install Proton into your user's Steam directory, see the install Proton locally section for details.

make redist - create a redistribute build (redist/) that can be copied to ~/.steam/root/compatibilitytools.d/.

make deploy - create a deployment build (deploy/). This is what we use to deploy Proton to Steam users via Steamworks.

make module=<module> module - build both 32- and 64-bit versions of the specified wine module. This allows rapid iteration on one module. This target is only useful after building Proton.

make dxvk / make vkd3d-proton - rebuild DXVK / vkd3d-proton.

Figuring Out What Failed To Build

Proton build system invokes builds of many subprojects in parallel. If one subprojects fails there can be thousands of lines printed by other sub-builds before the top level exits. This can make the real reason of the build failing hard to find.

Appending 2>&1 | tee build.log will log the full build output to a build.log file. Searching that file from the bottom up for occurrences of Error should point to the right area. E.g.:

make 2>&1 | tee build.log
grep -n '] Error [0-9]' build.log

11220:make: *** [../Makefile.in:465: /builds/proton/proton/build-dir/.kaldi-i386-configure] Error 1
12427:make: *** [../Makefile.in:1323: deploy] Error 2

Debug Builds

To prevent symbol stripping add UNSTRIPPED_BUILD=1 to the make invocation. This should be used only with a clean build directory.

E.g.:

mkdir ../debug-proton-build && cd ../debug-proton-build
../proton/configure.sh --enable-ccache --build-name=debug_build
make UNSTRIPPED_BUILD=1 install

ARM64 Builds

You need an ARM64 build machine and pass --target-arch=arm64 to configure.sh.

It's not possible to use the resulting builds in x86 Steam running via FEX.

Install Proton locally

Steam ships with several versions of Proton, which games will use by default or that you can select in Steam Settings' Steam Play page. Steam also supports running games with local builds of Proton, which you can install on your machine.

To install a local build of Proton into Steam, make a new directory in ~/.steam/root/compatibilitytools.d/ with a tool name of your choosing and place the directory containing your redistributable build under that path.

The make install target will perform this task for you, installing the Proton build into the Steam folder for the current user. You will have to restart the Steam client for it to pick up on a new tool.

A correct local tool installation should look similar to this:

compatibilitytools.d/my_proton/
├── compatibilitytool.vdf
├── filelock.py
├── LICENSE
├── proton
├── proton_dist.tar
├── toolmanifest.vdf
├── user_settings.sample.py
└── version

To enable your local build in Steam, go to the Steam Play section of the Settings window. If the build was correctly installed, you should see "proton-localbuild" in the drop-down list of compatibility tools.

Each component of this software is used under the terms of their licenses. See the LICENSE files here, as well as the LICENSE, COPYING, etc files in each submodule and directory for details. If you distribute a built version of Proton to other users, you must adhere to the terms of these licenses.

Debugging

Proton builds have their symbols stripped by default. You can switch to "debug" beta branch in Steam (search for Proton in your library, Properties... -> BETAS -> select "debug") or build without stripping (see Debug Builds section).

The symbols are provided through the accompanying .debug files which may need to be explicitly loaded by the debugging tools. For GDB there's a helper script wine/tools/gdbinit.py (source it) that provides load-symbol-files (or lsf for short) command which loads the symbols for all the mapped files.

For tips on debugging see docs/DEBUGGING-LINUX.md and docs/DEBUGGING-WINDOWS.md.

`compile_commands.json`

For use with clangd LSP server and similar tooling.

Projects built using cmake or meson (e.g. vkd3d-proton) automatically come with compile_commands.json. Wine also generates the file on its own via makedep.

Proton's build system collects all the compile_commands.json files in a build subdirectory named compile_commands/.

The paths are translated to point to the real source (i.e. not the rsynced copy). It still may depend on build directory for things like auto-generated config.h though and for wine it may be beneficial to run tools/make_requests in you source directories as those changes are not committed.

You can then configure your editor to use that file for clangd in a few ways:

directly - some editors/plugins allow you to specify the path to compile_commands.json
via .clangd file, e.g.

cd src/proton/wine/
cat > .clangd <<EOF
CompileFlags:
  CompilationDatabase: ../build/current-dev/compile_commands/wine-x86_64/
EOF

by symlinking:

ln -s ../build/current-dev/compile_commands/wine-x86_64/compile_commands.json .

Runtime Config Options

Proton can be tuned at runtime to help certain games run. The Steam client sets some options for known games using the STEAM_COMPAT_CONFIG variable. You can override these options using the environment variables described below.

The best way to set these environment overrides for all games is by renaming user_settings.sample.py to user_settings.py and modifying it appropriately. This file is located in the Proton installation directory in your Steam library (often ~/.steam/steam/steamapps/common/Proton #.#).

If you want to change the runtime configuration for a specific game, you can use the Set Launch Options setting in the game's Properties dialog in the Steam client. Set the variable, followed by %command%. For example, input "PROTON_USE_WINED3D=1 %command%" to use the OpenGL-based wined3d renderer instead of the Vulkan-based DXVK renderer.

To enable an option, set the variable to a non-0 value. To disable an option, set the variable to 0. To use Steam's default configuration, do not specify the variable at all.

All of the below are runtime options. They do not effect permanent changes to the Wine prefix. Removing the option will revert to the previous behavior.

Compat config string	Environment Variable	Description
	`PROTON_LOG`	Convenience method for dumping a useful debug log to `$PROTON_LOG_DIR/steam-$APPID.log`. Set to `1` to enable default logging, or set to a string to be appended to the default `WINEDEBUG` channels.
	`PROTON_LOG_DIR`	Output log files into the directory specified. Defaults to your home directory.
	`PROTON_WAIT_ATTACH`	Wait for a debugger to attach to steam.exe before launching the game process. To attach to the game process at startup, debuggers should be set to follow child processes.
	`PROTON_CRASH_REPORT_DIR`	Write crash logs into this directory. Does not clean up old logs, so may eat all your disk space eventually.
`wined3d`	`PROTON_USE_WINED3D`	Use OpenGL-based wined3d instead of Vulkan-based DXVK for d3d11, d3d10, and d3d9.
`nod3d11`	`PROTON_NO_D3D11`	Disable `d3d11.dll`, for d3d11 games which can fall back to and run better with d3d9.
`nod3d10`	`PROTON_NO_D3D10`	Disable `d3d10.dll` and `dxgi.dll`, for d3d10 games which can fall back to and run better with d3d9.
`dxvkd3d8`	`PROTON_DXVK_D3D8`	Use DXVK's `d3d8.dll`.
`nofsync`	`PROTON_NO_FSYNC`	Do not use futex-based in-process synchronization primitives. (Automatically disabled on systems with no `FUTEX_WAIT_MULTIPLE` support.)
	`PROTON_NO_NTSYNC`	Do not use ntsync.
	`HOST_LC_ALL`	Set value to a locale to override all other system locale settings for a game. This variable should be used instead of `LC_ALL`.
`disablenvapi`	`PROTON_DISABLE_NVAPI`	Disable NVIDIA's NVAPI GPU support library.
`nativevulkanloader`		Use the Vulkan loader shipped with the game instead of Proton's built-in Vulkan loader. This breaks VR support, but is required by a few games.
`forcelgadd`	`PROTON_FORCE_LARGE_ADDRESS_AWARE`	Force Wine to enable the LARGE_ADDRESS_AWARE flag for all executables. Enabled by default.
`heapdelayfree`	`PROTON_HEAP_DELAY_FREE`	Delay freeing some memory, to work around application use-after-free bugs.
`gamedrive`	`PROTON_SET_GAME_DRIVE`	Create an S: drive which points to the Steam Library which contains the game.
`noforcelgadd`		Disable forcelgadd. If both this and `forcelgadd` are set, enabled wins.
`oldglstr`	`PROTON_OLD_GL_STRING`	Set some driver overrides to limit the length of the GL extension string, for old games that crash on very long extension strings.
`vkd3dfl12`		Force the Direct3D 12 feature level to 12, regardless of driver support.
`vkd3dbindlesstb`		Put `force_bindless_texel_buffer` into `VKD3D_CONFIG`.
`nomfdxgiman`	`WINE_DO_NOT_CREATE_DXGI_DEVICE_MANAGER`	Enable hack to work around video issues in some games due to incomplete IMFDXGIDeviceManager support.
`noopwr`	`WINE_DISABLE_VULKAN_OPWR`	Enable hack to disable Vulkan other process window rendering which sometimes causes issues on Wayland due to blit being one frame behind.
`hidenvgpu`	`PROTON_HIDE_NVIDIA_GPU`	Force Nvidia GPUs to always be reported as AMD GPUs. Some games require this if they depend on Windows-only Nvidia driver functionality. See also DXVK's nvapiHack config, which only affects reporting from Direct3D.
	`WINE_FULLSCREEN_INTEGER_SCALING`	Enable integer scaling mode, to give sharp pixels when upscaling.
	`WINE_USE_KWIN_HACKS`	Enable KDE-specific windowing hacks that may improve experience with KDE older than 6.4 on Wayland and KDE older than 6.6 on X11.
`cmdlineappend:`		Append the string after the colon as an argument to the game command. May be specified more than once. Escape commas and backslashes with a backslash.
`xalia` or `noxalia`	`PROTON_USE_XALIA`	Enable Xalia, a program that can add a gamepad UI for some keyboard/mouse interfaces, or set to 0 to disable. The default is to enable it dynamically based on window contents.
`fnad3d11`	`FNA3D_FORCE_DRIVER=D3D11`	Force FNA to use D3D11 for rendering.
`seccomp`	`PROTON_USE_SECCOMP`	Note: Obsoleted in Proton 5.13. In older versions, enable seccomp-bpf filter to emulate native syscalls, required for some DRM protections to work.
`d9vk`	`PROTON_USE_D9VK`	Note: Obsoleted in Proton 5.0. In older versions, use Vulkan-based DXVK instead of OpenGL-based wined3d for d3d9.
`noesync`	`PROTON_NO_ESYNC`	Note: Obsoleted in Proton 11.0. In older versions, do not use eventfd-based in-process synchronization primitives.

hyprwm/Hyprland

Hyprland is an independent, highly customizable, dynamic tiling Wayland compositor that doesn't sacrifice on its looks.

Hyprland is a 100% independent, dynamic tiling Wayland compositor that doesn't sacrifice on its looks.

It provides the latest Wayland features, is highly customizable, has all the eyecandy, the most powerful plugins, easy IPC, much more QoL stuff than other compositors and more...

Install Quick Start Configure Contribute

Features

All of the eyecandy: gradient borders, blur, animations, shadows and much more
A lot of customization
100% independent, no wlroots, no libweston, no kwin, no mutter.
Custom bezier curves for the best animations
Powerful plugin support
Built-in plugin manager
Tearing support for better gaming performance
Easily expandable and readable codebase
Fast and active development
Not afraid to provide bleeding-edge features
Config reloaded instantly upon saving
Fully dynamic workspaces
Two built-in layouts and more available as plugins
Global keybinds passed to your apps of choice
Tiling/pseudotiling/floating/fullscreen windows
Special workspaces (scratchpads)
Window groups (tabbed mode)
Powerful window/monitor/layer rules
Socket-based IPC
Native IME and Input Panels Support
and much more...

Gallery

Special Thanks

wlroots - For powering Hyprland in the past

tinywl - For showing how 2 do stuff

Sway - For showing how 2 do stuff the overkill way

Vivarium - For showing how 2 do stuff the simple way

dwl - For showing how 2 do stuff the hacky way

Wayfire - For showing how 2 do some graphics stuff

bambulab/BambuStudio

PC Software for BambuLab and other 3D printers

BambuStudio

Bambu Studio is a cutting-edge, feature-rich slicing software.
It contains project-based workflows, systematically optimized slicing algorithms, and an easy-to-use graphic interface, bringing users an incredibly smooth printing experience.

Prebuilt Windows, macOS 64-bit and Linux releases are available through the github releases page.

Bambu Studio is based on PrusaSlicer by Prusa Research, which is from Slic3r by Alessandro Ranellucci and the RepRap community.

See the wiki and the documentation directory for more information.

What are Bambu Studio's main features?

Key features are:

Basic slicing features & GCode viewer
Multiple plates management
Remote control & monitoring
Auto-arrange objects
Auto-orient objects
Hybrid/Tree/Normal support types, Customized support
multi-material printing and rich painting tools
multi-platform (Win/Mac/Linux) support
Global/Object/Part level slicing parameters

Other major features are:

Advanced cooling logic controlling fan speed and dynamic print speed
Auto brim according to mechanical analysis
Support arc path(G2/G3)
Support STEP format
Assembly & explosion view
Flushing transition-filament into infill/object during filament change

How to compile

Following platforms are currently supported to compile:

Windows 64-bit, Compile Guide
Mac 64-bit, Compile Guide
Linux, Compile Guide
- currently we only provide linux appimages on github releases for Ubuntu/Fedora, and a flathub version can be used for all the linux platforms

Report issue

You can add an issue to the github tracker if it isn't already present.

License

Bambu Studio is licensed under the GNU Affero General Public License, version 3. Bambu Studio is based on PrusaSlicer by PrusaResearch.

PrusaSlicer is licensed under the GNU Affero General Public License, version 3. PrusaSlicer is owned by Prusa Research. PrusaSlicer is originally based on Slic3r by Alessandro Ranellucci.

Slic3r is licensed under the GNU Affero General Public License, version 3. Slic3r was created by Alessandro Ranellucci with the help of many other contributors.

The GNU Affero General Public License, version 3 ensures that if you use any part of this software in any way (even behind a web server), your software must be released under the same license.

The bambu networking plugin is based on non-free libraries. It is optional to the Bambu Studio and provides extended networking functionalities for users. By default, after installing Bambu Studio without the networking plugin, you can initiate printing through the SD card after slicing is completed.

notepad-plus-plus/notepad-plus-plus

Notepad++ official repository

What is Notepad++ ?

Notepad++ is a free (free as in both "free speech" and "free beer") source code editor and Notepad replacement that supports several programming languages and natural languages. Running in the MS Windows environment, its use is governed by GPL License.

See the Notepad++ official site for more information.

Notepad++ GPG Release Key

Since the release of version 7.6.5 Notepad++ is signed using GPG with the following key:

Signer: Notepad++
E-mail: don.h@free.fr
Key ID: 0x8D84F46E
Key fingerprint: 14BC E436 2749 B2B5 1F8C 7122 6C42 9F1D 8D84 F46E
Key type: RSA 4096/4096
Created: 2019-03-11
Expires: 2027-03-13

https://github.com/notepad-plus-plus/notepad-plus-plus/blob/master/nppGpgPub.asc

Supported OS

All the Windows systems still supported by Microsoft are supported by Notepad++. However, not all Notepad++ users can or want to use the newest system. Here is the Supported systems information you may need in case you are one of them.

Build Notepad++

Please follow build guide to build Notepad++ from source.

Contribution

Contributions are welcome. Be mindful of our Contribution Rules to increase the likelihood of your contribution getting accepted.

Notepad++ Contributors

qbittorrent/qBittorrent

qBittorrent BitTorrent client

qBittorrent - A BitTorrent client in Qt

Description:

qBittorrent is a bittorrent client programmed in C++ / Qt that uses libtorrent (sometimes called libtorrent-rasterbar) by Arvid Norberg.

It aims to be a good alternative to all other bittorrent clients out there. qBittorrent is fast, stable and provides unicode support as well as many features.

The free IP to Country Lite database by DB-IP is used for resolving the countries of peers. The database is licensed under the Creative Commons Attribution 4.0 International License.

Installation:

Refer to the INSTALL file.

Public key:

Starting from v3.3.4 all source tarballs and binaries are signed.
The key currently used is 4096R/5B7CC9A2 with fingerprint D8F3DA77AAC6741053599C136E4A2D025B7CC9A2.
You can also download it from here.
PREVIOUSLY the following key was used to sign the v3.3.4 source tarballs and v3.3.4 Windows installer only: 4096R/520EC6F6 with fingerprint F4A5FD201B117B1C2AB590E2A1ACCAE4520EC6F6.

Misc:

For more information please visit: https://www.qbittorrent.org

or our wiki here: https://wiki.qbittorrent.org

Use the forum for troubleshooting before reporting bugs: https://forum.qbittorrent.org

Please report any bug (or feature request) to: https://bugs.qbittorrent.org

Official IRC channel: #qbittorrent on irc.libera.chat

sledgehammer999 <sledgehammer999@qbittorrent.org>

WerWolv/ImHex

🔍 A Hex Editor for Reverse Engineers, Programmers and people who value their retinas when working at 3 AM.

A Hex Editor for Reverse Engineers, Programmers and people who value their retinas when working at 3 AM.
/ˈɪmhɛks/

Supporting

If you like my work, please consider supporting me on GitHub Sponsors, Ko-Fi or PayPal. Thanks a lot!

Notable Sponsors


	JetBrains, providing us with free All Products Pack licenses for development
	SignPath, providing us with free Code Signing Certificates for our Windows builds
	Amazon, providing us with free AWS Cloud Credits for our CI

Would you like to appear here as well? Contact us at imhex@werwolv.net!

Screenshots

More Screenshots

Features

Featureful hex view

Byte patching
Patch management
Infinite Undo/Redo
"Copy bytes as..."
- Bytes
- Hex string
- C, C++, C#, Rust, Python, Java & JavaScript array
- ASCII-Art hex view
- HTML self-contained div
Simple string and hex search
Goto from start, end and current cursor position
Colorful highlighting
- Configurable foreground highlighting rules
- Background highlighting using patterns, find results and bookmarks
Displaying data as a list of many different types
- Hexadecimal integers (8, 16, 32, 64 bit)
- Signed and unsigned decimal integers (8, 16, 32, 64 bit)
- Floats (16, 32, 64 bit)
- RGBA8 Colors
- HexII
- Binary
Decoding data as ASCII and custom encodings
- Built-in support for UTF-8, UTF-16, ShiftJIS, most Windows encodings and many more
Paged data view

Custom C++-like pattern language for parsing highlighting a file's content

Automatic loading based on MIME types and magic values
Arrays, pointers, structs, unions, enums, bitfields, namespaces, little and big endian support, conditionals and much more!
Useful error messages, syntax highlighting and error marking
Support for visualizing many different types of data
- Images
- Audio
- 3D Models
- Coordinates
- Time stamps

Theming support

Doesn't burn out your retinas when used in late-night sessions
- Dark mode by default, but a light mode is available as well
Customizable colors and styles for all UI elements through shareable theme files
Support for custom fonts

Importing and Exporting data

Base64 files
IPS and IPS32 patches
Markdown reports
Binary arrays for various programming languages

Data Inspector

Interpreting data as many different types with endianness, decimal, hexadecimal and octal support and bit inversion
- Unsigned and signed integers (8, 16, 24, 32, 48, 64 bit)
- Floats (16, 32, 64 bit)
- Signed and Unsigned LEB128
- ASCII, Wide and UTF-8 characters and strings
- time32_t, time64_t, DOS date and time
- GUIDs
- RGBA8 and RGB65 Colors
Copying and modifying bytes through the inspector
Adding new data types through the pattern language
Support for hiding rows that aren't used

Node-based data pre-processor

Modify, decrypt and decode data before it's being displayed in the hex editor
Modify data without touching the underlying source
Support for adding custom nodes

Loading data from many different data sources

Local Files
- Support for huge files with fast and efficient loading
Raw Disks
- Loading data from raw disks and partitions
GDB Server
- Access the RAM of a running process or embedded devices through GDB
Intel Hex and Motorola SREC data
Base64 encoded data
UDP Packets
- Support for displaying raw data received over UDP
Process Memory
- Inspect the entire address space of a running process
Remote Files over SSH with SFTP
- Support for loading files from remote servers using SSH and SFTP

Data searching

Support for searching the entire file or only a selection
String extraction
- Option to specify minimum length and character set (lower case, upper case, digits, symbols)
- Option to specify encoding (ASCII, UTF-8, UTF-16 big and little endian)
Sequence search
- Search for a sequence of bytes or characters
- Option to ignore character case
Regex search
- Search for strings using regular expressions
Binary Pattern
- Search for sequences of bytes with optional wildcards
Numeric Value search
- Search for signed/unsigned integers and floats
- Search for ranges of values
- Option to specify size and endianness
- Option to ignore unaligned values

Data hashing support

Many different algorithms available
- CRC8, CRC16 and CRC32 with custom initial values and polynomials
  - Many default polynomials available
- MD5
- SHA-1, SHA-224, SHA-256, SHA-384, SHA-512
- Adler32
- AP
- BKDR
- Bernstein, Bernstein1
- DEK, DJB, ELF, FNV1, FNV1a, JS, PJW, RS, SDBM
- OneAtTime, Rotating, ShiftAndXor, SuperFast
- Murmur2_32, MurmurHash3_x86_32, MurmurHash3_x86_128, MurmurHash3_x64_128
- SipHash64, SipHash128
- XXHash32, XXHash64
- Tiger, Tiger2
- Blake2B, Blake2S
Hashing of specific regions of the loaded data
Hashing of arbitrary strings

Diffing support

Compare data of different data sources
Difference highlighting
Table view of differences

Integrated disassembler

Support for all architectures supported by Capstone
- ARM32 (ARM, Thumb, Cortex-M, AArch32)
- ARM64
- MIPS (MIPS32, MIPS64, MIPS32R6, Micro)
- x86 (16-bit, 32-bit, 64-bit)
- PowerPC (32-bit, 64-bit)
- SPARC
- IBM SystemZ
- xCORE
- M68K
- TMS320C64X
- M680X
- Ethereum
- RISC-V
- WebAssembly
- MOS65XX
- Berkeley Packet Filter
Support for writing custom disassemblers for your own architectures

Bookmarks

Support for bookmarks with custom names and colors
Highlighting of bookmarked region in the hex editor
Jump to bookmarks
Open content of bookmark in a new tab
Add comments to bookmarks

Featureful data analyzer and visualizer

File magic-based file parser and MIME type database
Byte type distribution graph
Entropy graph
Highest and average entropy
Encrypted / Compressed file detection
Digram and Layered distribution graphs

YARA Rule support

Scan a file for vulnerabilities with official yara rules
Highlight matches in the hex editor
Jump to matches
Apply multiple rules at once

Helpful tools

Itanium, MSVC, Rust and D-Lang demangler based on LLVM
ASCII table
Regex replacer
Mathematical expression evaluator (Calculator)
Graphing calculator
Hexadecimal Color picker with support for many different formats
Base converter
Byte swapper
UNIX Permissions calculator
Wikipedia term definition finder
File utilities
- File splitter
- File combiner
- File shredder
IEEE754 Float visualizer
Division by invariant multiplication calculator
TCP Client/Server
Euclidean algorithm calculator
HTTP Requests

Built-in Content updater

Download all files found in the database directly from within ImHex
- Pattern files for decoding various file formats
- Libraries for the pattern language
- Magic files for file type detection
- Custom data processor nodes
- Custom encodings
- Custom themes
- Yara rules

Modern Interface

Support for multiple workspaces
Support for custom layouts
Detachable windows

Easy to get started

Support for many different languages
Simplified mode for beginners
Extensive documentation
Many example files available on the Database
Achievements guiding you through the features of ImHex
Interactive tutorials

Pattern Language

The Pattern Language is the completely custom programming language developed for ImHex. It allows you to define structures and data types in a C-like syntax and then use them to parse and highlight a file's content.

Source Code: Link
Documentation: Link

Database

For format patterns, libraries, magic and constant files, check out the ImHex-Patterns repository.

Feel free to PR your own files there as well!

Requirements

To use ImHex, the following minimal system requirements need to be met.

Important

ImHex requires a GPU with OpenGL 3.0 support in general. There are releases available (with the -NoGPU suffix) that are software rendered and don't require a GPU, however these can be a lot slower than the GPU accelerated versions.

If possible at all, make ImHex use the dedicated GPU on your system instead of the integrated one. ImHex will usually run fine with integrated GPUs as well but certain Intel HD GPU drivers on Windows are known to cause graphical artifacts.

OS:
- Windows: Windows 7 or higher (Windows 10/11 recommended)
- macOS: macOS 15 (Sequoia) or higher,
  - Lower versions should still work too, but you'll need to compile ImHex yourself. The release binaries will NOT work due to GitHub not having any macOS 15 or lower CI runners available.
  - The macOS build is not signed and will require you to manually allow them in the Security & Privacy settings.
- Linux: "Modern" Linux. The following distributions have official releases available. Other distros are supported through the AppImage, Flatpak and Snap releases.
  - Ubuntu and Debian
  - Fedora
  - RHEL/AlmaLinux
  - Arch Linux
  - Basically any other distro will work as well when compiling ImHex from sources.
- FreeBSD: Tested on FreeBSD 14.3
  - Other versions will most likely work too but are untested
CPU: Officially supported are x86, AMD64 and ARM64, though any Little Endian CPU should work.
GPU: OpenGL 3.0 or higher
- Integrated Intel HD iGPUs are supported, however certain drivers are known to cause various graphical artifacts, especially on Windows. Use at your own risk.
- In case you don't have a GPU available, there are software rendered releases available for Windows and macOS
RAM: ~50MiB, more is required for more complex analysis
Storage: ~100MiB

Installing

Information on how to install ImHex can be found in the Install guide

Compiling

To compile ImHex on any platform, GCC (or Clang) is required with a version that supports C++23 or higher. Windows and Linux releases are being built using latest available GCC. MacOS releases are being built using latest available LLVM Clang.

Important to note is, the MSVC and AppleClang compilers are both NOT supported since they're both generally severely outdated and lack features GCC and LLVM Clang have.

Note

Many dependencies are bundled into the repository using submodules so make sure to clone it using the --recurse-submodules option. All dependencies that aren't bundled, can be installed using the dependency installer scripts found in the /dist folder.

For more information, check out the Compiling guide.

Contributing

See Contributing

Plugin development

To develop plugins for ImHex, use the following template project to get started. You then have access to the entirety of libimhex as well as the ImHex API and the Content Registry to interact with ImHex or to add new content. To build a plugin, you will need to use our SDK

Getting the SDK locally

You can build the SDK by compiling ImHex like this:

cmake -G Ninja -DIMHEX_BUNDLE_PLUGIN_SDK=ON -B build
cd build
DESTDIR=install ninja install The SDK will then be available at install/usr/local/share/imhex/sdk. You will need to set the variable IMHEX_SDK_PATH to that (absolute) path.

Getting the SDK in a Github Actions CI

You can use this action to automatically download the SDK to your Github Runner

ImHex Plugin Template

Credits

Contributors

AxCut for a gigantic amount of contributions to the Pattern Text Editor and tons of other parts of ImHex
iTrooz for getting ImHex onto the Web as well as hundreds of contributions in every part of the project
jumanji144 for huge contributions to the Pattern Language and ImHex's infrastructure
Mary for her immense help porting ImHex to macOS and help during development
Roblabla for adding MSI Installer support to ImHex
Mailaender for getting ImHex onto Flathub
Everybody else who has reported issues on Discord or GitHub that I had great conversations with 😃

Dependencies

Thanks a lot to ocornut for their amazing Dear ImGui which is used for building the entire interface
- Thanks to epezent for ImPlot used to plot data in various places
- Thanks to Nelarius for ImNodes used as base for the data processor
- Thanks to BalazsJako for ImGuiColorTextEdit used for the pattern language syntax highlighting
Thanks to nlohmann for their json library used for configuration files
Thanks to vitaut for their libfmt library which makes formatting and logging so much better
Thanks to btzy for nativefiledialog-extended and their great support, used for handling file dialogs on all platforms
Thanks to danyspin97 for xdgpp used to handle folder paths on Linux
Thanks to aquynh for capstone which is the base of the disassembly window
Thanks to rxi for microtar used for extracting downloaded store assets
Thanks to VirusTotal for Yara used by the Yara plugin
Thanks to Martinsos for edlib used for sequence searching in the diffing view
Thanks to ron4fun for HashLibPlus which implements every hashing algorithm under the sun
Thanks to mackron for miniaudio used to play audio files
Thanks to all other groups and organizations whose libraries are used in ImHex

License

The biggest part of ImHex is under the GPLv2-only license. Notable exceptions to this are the following parts which are under the LGPLv2.1 license:

/lib/libimhex: The library that allows Plugins to interact with ImHex.
/plugins/ui: The UI plugin library that contains some common UI elements that can be used by other plugins

The reason for this is to allow for proprietary plugins to be developed for ImHex.

Code Signing Policy

Free code signing provided by SignPath.io, certificate by SignPath Foundation.

This program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it.

People with direct push access

jarczakpawel/BMCU-C-PJARCZAK

BMCU 370C (Hall) firmware for Bambu Lab A1 / A1 mini / P1S with buffer calibration - all known issues fixed, 100% AMS-compatible behavior.

BMCU Firmware – Calibration and Compatibility Notes

This BMCU firmware has been tested and verified with the latest Bambu Lab A1 firmware.

IMPORTANT: The printer must be configured as AMS, not AMS Lite. Using AMS Lite will cause incompatibility issues.

Support

Bambu Lab continues tightening compatibility around BMCU, and there is a growing risk that BMCU may eventually become unusable in that ecosystem.

To prepare for that, I want to build BMCU support for open-source Klipper-based printers.

I am currently raising funds to buy a test printer for this work.

The $500 goal does not need to be reached in full. If I manage to save the remaining amount myself, I will cover the rest out of my own pocket.

Support on Ko-fi · Support via Revolut

Direct Revolut support avoids Ko-fi fees, so more of your contribution goes directly to the project.

❗ IMPORTANT - FIRST START (V10.3+) ❗

At the first startup after flashing, all channels must be empty.

From V10.3, the firmware calibrates empty-channel detection during first boot.

If you flashed it with filament inserted:

remove all filament
hold any one buffer for about 5 seconds to re-calibrate

❗ Warning for 2nd generation printers

A lot of people make a mistake because the drawings are misleading, and it is not always clear from the diagrams whether they show the plug or the socket. As a result, Signal A and Signal B often get connected the wrong way around.

If your BMCU is not detected by a 2nd generation printer, try swapping Signal A and Signal B - but make sure you know exactly what you are doing.

HMS WARNING STATUS

This firmware version triggers an HMS warning immediately after printer startup.

Important clarification:

This HMS warning does NOT block BMCU operation
It does NOT require restarting the printer
It does NOT affect printing
The printer works normally despite the warning
The issue is purely visual / informational (HMS icon only)

At the moment, the HMS warning is known and accepted behavior in this firmware version.

If the HMS warning in Bambu Studio annoys you: I made a Bambu Studio build that bypasses this specific AMS compatibility warning, so you do not see it anymore. Other HMS warnings will still be visible (if they happen), so HMS remains useful.

https://github.com/jarczakpawel/BambuStudio-BMCU

Supported printers

Correct operation has been confirmed on both 1st generation and 2nd generation printers.

1st generation printers

Support is confirmed for 1st generation printers.

2nd generation printers

Correct operation has been confirmed on:

Bambu Lab P2S
Bambu Lab H2D

At this point, it looks like it should work on all printers from both generations.

Download

Please download ready-to-use firmware from the "Releases" section (right side of the GitHub page). All firmware variants are generated there together with .txt guides that explain which build you should choose.

Start by selecting the correct printer mode folder first (standard(A1) or high_force_load(P1S)), then choose AUTOLOAD / RGB / slots as usual.

Flashing

To flash any version of the BMCU (USB or TTL) on:

Windows
Linux
macOS
Android

use BMCU Flasher:

https://github.com/jarczakpawel/BMCU-Flasher

Precompiled binaries are available in the Releases section.

The flashing process is very simple and does not require wchisptool.

You can flash firmware in two ways:

Online flashing directly from the built-in wizard (recommended)
→ the flasher downloads the correct firmware automatically, so you do not need to download any .bin files manually.
Local flashing using a firmware file you downloaded yourself.

The flasher also supports Android, so you can even flash the BMCU directly from your phone 🙂

IMPORTANT:

Do NOT flash the BMCU while it is connected to the printer.
Do NOT connect or disconnect the BMCU while the printer is powered on (risk of damaging the BMCU and/or the printer mainboard).

SOLO firmware

Example file:

solo_0.095f.bin

This firmware is intended for single BMCU (SOLO) operation.

Recommended for single-BMCU setups
Filament retraction length: 9.5 cm

Filament retraction explanation

Filament retraction must be calculated from the end of the AMS splitter inside the printer (the plastic AMS part where four PTFE tubes enter).

Example:

Distance from BMCU to the end of the AMS splitter: approximately 9.0 cm
SOLO firmware retracts the filament about 0.5 cm past the splitter
Total retraction length: 9.5 cm

When calculating your own retraction length:

Always measure from the end of the AMS splitter
Add the required distance plus approximately 9 cm, depending on your setup

AMS_A / AMS_B / AMS_C / AMS_D firmware

These firmware versions are intended for:

Multi-BMCU setups
Longer filament retraction distances

If you want to use SOLO mode with a longer retraction, use AMS_A instead of SOLO.

Calibration (first start)

Correct calibration is mandatory. Without proper calibration, BMCU will not work correctly.

The calibration process is shown in the following video:

https://www.youtube.com/watch?v=Hn_DNzSmhuc

Follow the calibration steps shown in the video carefully.

Re-calibration

You can recalibrate the BMCU at any time.

Steps:

Remove all filaments from all channels
Hold any one buffer in position for approximately 5 seconds

Safety and usage notes

Do not flash BMCU while it is connected to the printer
Do not disconnect BMCU while the printer is powered on
Do not update printer firmware while BMCU is connected
Connect/disconnect the BMCU ONLY when the printer is completely powered off (unplugged). Doing this while powered can damage the BMCU and/or the printer mainboard.

These recommendations are based on community reports. Not all failure scenarios have been tested.

Changing the printer mode from AMS Lite to AMS while BMCU was connected did not cause issues in testing, but this is not recommended.

Disclaimer

You are using this firmware and performing any modifications at your own risk. Make sure you understand what you are doing. I am not responsible for any damage, failed prints, hardware issues, or data loss.

Before opening a bug report

Please verify the basics first:

Make sure you flashed the correct firmware variant and followed the flashing tutorial correctly.
Make sure you really have BMCU 370C with Hall sensors.
- The only reliable verification is to open the module and inspect the PCB.
- Some sellers mix modules and try to get rid of older 370x boards - sometimes 1-2 modules in the set can be 370x.
If you have printer-side issues:
- confirm you are on the latest printer firmware
- do a factory reset (this often fixes weird AMS-related behavior)
If filament detection behaves strangely:
- boot the printer once without BMCU connected
- then connect BMCU and test again
Do a few real tests before creating a thread. Printers can have unrelated issues (rare, but happens) - some users cannot even update printer firmware automatically and must do it via SD card.

Bug reports

If you encounter a real bug, you may report it. This firmware has undergone solid testing, and no issues are expected.

Changelog

V10.5

User-visible changes

Added automatic filament unload when the buffer is lifted manually.
The serial is generated from the MCU hardware UID, so devices no longer share the same SN.
Calibration now performs a full NVM cleanup.
Fixed the rare issue where the system LED could blink incorrectly on some BMCU units.
Fixed the external fan issue on Bambu Lab P2S.

V10.4

User-visible changes

Added support for Bambu Lab P2S.
- Verified to work correctly in real tests.
- The H2 series will most likely also work as well, because 1st generation AMS support is confirmed there.

Fixes

"filament in use" flag is now cleared correctly when filament runs out during printing.
Added support for retraction when the buffer is pulled up manually, even when there is no filament inside.

V10.3

User-visible changes

Added new firmware mode: soft_load(A1).
- Intended mainly for A1 / A1 Mini users.
- Uses lower filament loading force than standard(A1).
- Useful for some BMCU units with weaker lever springs, where stronger loading can cause clicking / grinding during filament load.
Improved empty-channel detection calibration.
- The firmware now calibrates and stores the "no filament" detection point separately for each channel.
- This improves reliability on hardware variants where idle detection voltage differs between channels/modules.
Improved calibration behavior:
- calibration now also detects and saves Hall polarity per channel
- magnet polarity is automatically detected during calibration and stored, so it no longer matters which way the magnet is inserted in the buffer

Stability and behavior improvements

Fixed PWM timer preload configuration on all motor channels.
- PWM updates are now buffered correctly before timer update events.
Improved AS5600 update timing.
- Sensor polling is now rate-limited to about 1 ms
- more stable speed calculation
- lower unnecessary CPU load
Improved internal timing paths by reusing shared tick snapshots in the main motion loop.
- less timing jitter
- more consistent runtime behavior
Improved high-load / jam timing logic during on_use.
- high PWM accumulation now uses microsecond precision instead of millisecond buckets
Improved motion loop time-step handling.
- uses wrap-safe tick delta
- clamps oversized time steps
- avoids running motor control with invalid zero-step timing

Notes

soft_load(A1) is not meant as the default for everyone.
If filament gets rejected because push force is too weak, switch back to standard(A1) and use a stronger lever spring.
On some A1 / A1 Mini units, soft_load(A1) works very well and can be used permanently.

V10.2

User-visible changes

Fixed a problem where filament run-out could incorrectly trigger a jam condition.
When filament ended, the motor could run continuously and eventually enter jam protection, which blocked the automatic filament refill.
Reworked jam protection logic:
- real filament jams are now detected separately from temporary motor stops
- high motor load alone no longer falsely triggers a jam
Improved flash persistence system (less unnecessary flash rewriting).
Improved ADC/DMA processing:
- faster value updates
- lower CPU overhead
- smoother runtime behavior
Various timing and stability improvements.

Technical changes

Filament metadata flash storage redesigned.
- append-only journal instead of rewriting a full flash page
- each record: 40 bytes (10 words)
- CRC32 validation
- 6 records per flash page
- page erase only when the page becomes full
  This significantly reduces flash wear and makes writes power-loss safe.
Loaded-channel persistence reworked into a lightweight slot log to reduce erase cycles.
Added skip-if-unchanged logic to avoid unnecessary flash writes.
Simplified and optimized ADC DMA update/publish path.
CRC tables moved to static compile-time tables (no runtime generation).
Cleanup of timing paths using wrap-safe 32-bit timers.
Several other smaller fixes and internal optimizations.

V10

User-visible changes

Improved spool jam handling: jam is detected immediately, the print is paused, the printer waits for you to fix the snag/tangle, then you can resume normally without ruining the print.

Flash / persistence (wear + reliability)

State (loaded channel) persistence reworked into an append-only slot log: 8 bytes per update, up to 192 updates before any page erase (~192x fewer erase cycles vs rewriting a whole 256B page per update).
Filament metadata persistence reworked into a small CRC-protected log: 64B per update, 2 pages per filament (8 records) -> ~8x fewer erase cycles vs erasing a whole 256B page on every change.
Per-filament saves: only the modified channel is written (reduces unnecessary flash writes).
Power-loss safe commits: records are validated and partially-written data is ignored.

V9

User-visible changes

Increased filament loading force for improved reliability during filament insertion.
Improved filament loading behavior on some materials (e.g. Sunlu PLA+ and similar filaments) where loading characteristics differ from standard PLA/PETG.
Added protection against spool jams:
- Lock mode activates if the buffer drops too low during printing.
- Lock mode also activates if the motor runs at high speed continuously for ~8 seconds.
- The lock is automatically released once the buffer returns to the neutral position.
- Prevents prolonged motor overrun when filament movement is blocked.

V8

User-visible changes

Supported print resume after a printer power reset / power loss (printing can be resumed properly).
Improved behavior for P1S (loading problems due to long/bent PTFE path).
Added AUTOLOAD support for single-switch PCB boards:
- Triggered by pressing the buffer ("buffer tap").
- Starts filament loading exactly like the external switch trigger.
More stable loading process overall.
Improved support for low-torque BMCU variants.

V7

User-visible changes

Remember loaded filaments (persistent state).
You can load filament and safely power off the printer.
This allows you to disable the automatic unload-at-end behavior in G-code (if you often print with one filament), keeping filament loaded until you actually need to change it.
More info here: https://wiki.bambulab.com/en/ams/manual/ams-not-unloading-to-save-filament
100% solved filament loading problems. The system is stable and consistent across hardware variants.
Filament RGB colors. Modules/LEDs can display the configured filament color.

AUTOLOAD (short)

How AUTOLOAD works

DM (two microswitches):
- Touch first switch → AUTOLOAD starts (you may need a light manual push until gears grab).
- BMCU feeds filament until the second switch (behind extruder) confirms fully inserted.
- Then it feeds 120 mm to make it print-ready.
- Anti-snag protection: buffer position is monitored; if the filament catches on housing / PTFE edge, it retracts to safe position and retries (3 retries).
Single-switch boards:
- Stage 1 is manual (no second switch to confirm fully-in).
- Once filament is fully in the extruder, Stage 2 behaves the same (incl. anti-snag protection).

Technical changes

ADC_DMA upgraded (ADC1 + ADC2 in parallel):
- Regular simultaneous mode: ADC1+ADC2 scan channels in parallel to reduce noise and increase throughput.
- Lower noise enabled smaller filtering and faster stable readout.
- Full filtered update time: ~5 ms instead of ~28 ms.
AS5600 reading correctness improved (robustness and stability of reads).
Timer/tick safety (wrap safety): all time comparisons reviewed to be correct under wrap-around.
Final stabilization and cleanup: overall behavior is faster and more deterministic than previous releases.
There were more fixes in V7 as well; easiest is to check the commit history.

Final note: all known issues were ultimately resolved. BMCU is fully stable and significantly faster vs older firmware. At this moment I do not expect any further fixes.

V6

Framework

Dropped Arduino Core (PlatformIO: framework = arduino) - the whole firmware was rewritten to pure CH32 (WCH SDK / noneos).
Direct use of hardware timers, DMA and interrupts - no Arduino delays, no random timing, deterministic real-time behavior.
Faster and correct flash operations (WCH Fast API) - stable writes, faster, without corrupting neighboring data.

ADC_DMA

Separated DMA writes from CPU reads - previously reads happened while DMA was overwriting the buffer.
Filter is computed in the background (DMA half/full), not during readout - previously get_value() blocked CPU and broke timing.
Constant CPU load - previously larger filter window slowed the system down.
DMA error handling

BUS (BambuBus + AHUB)

Fixed RX/TX buffer race (reading and overwriting the same buffer at the same time).
Snapshot-based parsing instead of working on a live buffer
Deterministic frame handling timing - constant CPU cost, independent from packet length.
Robustness against transmission errors - a bad packet does not break the whole system state.

Flash / NVM

Flash written page-by-page (256B) instead of erasing/programming the whole sector (4KB)
Write only when data actually changed
Hardware CRC for flash + verification on read
AMS data split into separate records - changing one filament does not rewrite the whole structure.

Soft-I2C / AS5600

Rewritten from Arduino, removed timing bugs and Arduino "magic".
Correct ACK/NACK, START/STOP, recovery handling
Hard isolation of channels with errors

Motion / mechanics

Smoother motor control
Added calibration buffers - filament stays in a neutral position, without unnecessary tension.
Better state transitions - no jerks and no sudden braking.

Misc

CRC8 / CRC16 rewritten to simple C + lookup tables - faster, deterministic, no objects and no runtime init.
Partially de-spaghettified includes
and many more - firmware prepared for further development

Final note

This firmware started as a personal CH32 learning project. During development it grew far beyond the original scope because working on BMCU turned out to be genuinely enjoyable.

Many solutions are intentionally overengineered. Everything was implemented primarily for personal use and experimentation.

The firmware has been used extensively during development, and no practical issues were observed in real-world usage.

ml-explore/mlx

MLX: An array framework for Apple silicon

MLX

Quickstart | Installation | Documentation | Examples

MLX is an array framework for machine learning on Apple silicon, brought to you by Apple machine learning research.

Some key features of MLX include:

Familiar APIs: MLX has a Python API that closely follows NumPy. MLX also has fully featured C++, C, and Swift APIs, which closely mirror the Python API. MLX has higher-level packages like mlx.nn and mlx.optimizers with APIs that closely follow PyTorch to simplify building more complex models.
Composable function transformations: MLX supports composable function transformations for automatic differentiation, automatic vectorization, and computation graph optimization.
Lazy computation: Computations in MLX are lazy. Arrays are only materialized when needed.
Dynamic graph construction: Computation graphs in MLX are constructed dynamically. Changing the shapes of function arguments does not trigger slow compilations, and debugging is simple and intuitive.
Multi-device: Operations can run on any of the supported devices (currently the CPU and the GPU).
Unified memory: A notable difference from MLX and other frameworks is the unified memory model. Arrays in MLX live in shared memory. Operations on MLX arrays can be performed on any of the supported device types without transferring data.

MLX is designed by machine learning researchers for machine learning researchers. The framework is intended to be user-friendly, but still efficient to train and deploy models. The design of the framework itself is also conceptually simple. We intend to make it easy for researchers to extend and improve MLX with the goal of quickly exploring new ideas.

The design of MLX is inspired by frameworks like NumPy, PyTorch, Jax, and ArrayFire.

Examples

The MLX examples repo has a variety of examples, including:

Transformer language model training.
Large-scale text generation with LLaMA and finetuning with LoRA.
Generating images with Stable Diffusion.
Speech recognition with OpenAI's Whisper.

Quickstart

See the quick start guide in the documentation.

Installation

MLX is available on PyPI. To install MLX on macOS, run:

pip install mlx

To install the CUDA backend on Linux, run:

pip install mlx[cuda]

To install a CPU-only Linux package, run:

pip install mlx[cpu]

Checkout the documentation for more information on building the C++ and Python APIs from source.

Contributing

Check out the contribution guidelines for more information on contributing to MLX. See the docs for more information on building from source, and running tests.

We are grateful for all of our contributors. If you contribute to MLX and wish to be acknowledged, please add your name to the list in your pull request.

Citing MLX

The MLX software suite was initially developed with equal contribution by Awni Hannun, Jagrit Digani, Angelos Katharopoulos, and Ronan Collobert. If you find MLX useful in your research and wish to cite it, please use the following BibTex entry:

@software{mlx2023,
  author = {Awni Hannun and Jagrit Digani and Angelos Katharopoulos and Ronan Collobert},
  title = {{MLX}: Efficient and flexible machine learning on Apple silicon},
  url = {https://github.com/ml-explore},
  version = {0.0},
  year = {2023},
}

MaaAssistantArknights/MaaAssistantArknights

《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.

MAA

简体中文 | 繁體中文 | English | 日本語 | 한국어

MAA 的意思是 MAA Assistant Arknights

一款明日方舟游戏小助手

基于图像识别技术，一键完成全部日常任务！

绝赞更新中 ✿✿ヽ(°▽°)ノ✿

下载与安装

请阅读文档后前往官网或 Releases 下载，并参考新手上路进行安装。

亮点功能

理智作战，掉落识别及上传企鹅物流，一图流
智能基建换班，自动计算干员效率，单设施内最优解；同时也支持自定义排班
自动公招，可选使用加急许可，一次全部刷完！公招数据自动上传企鹅物流，一图流
支持手动识别公招界面，方便对高星公招做出选择 ~~（你的这个高资回费出的是推王呢还是推王呢）~~
支持识别干员列表，统计已有和未有干员及潜能，并在公招识别显示
支持识别养成材料，并导出至企鹅物流刷图规划、明日方舟工具箱、ARK-NIGHTS 干员培养表
访问好友、收取信用及购物、领取日常奖励等，一键全日常自动长草
肉鸽全自动刷源石锭和等级，自动烧水和凹直升，智能识别干员及练度
选择作业 JSON 文件，自动抄作业，视频演示
支持 C, Python, Java, Rust, Golang, Java HTTP, Rust HTTP 等多种接口，方便集成调用，自定义你的 MAA！

话不多说，看图！

使用说明

功能介绍

请参阅用户手册。

外服支持

目前国际服（美服）、日服、韩服、繁中服的绝大部分功能均已支持。但由于外服用户较少及项目人手不足，很多功能并没有进行全面的测试，所以请自行体验。
若您遇到了 Bug，或对某个功能有强需求，欢迎在 Issues 和讨论区催更；或加入我们一起建设 MAA！请参阅外服适配教程

CLI 支持

MAA 支持命令行界面（CLI）操作，支持 Linux，macOS 和 Windows，可用于自动化脚本或在无图形界面的服务器上使用。请参阅 CLI 使用指南

加入我们

主要关联项目

全新框架：MaaFramework
作业站前端：zoot-plus-frontend
作业站后端：ZootPlusBackend
官网：前端
深度学习：MaaAI

多语言 (i18n)

MAA 以中文（简体）为第一语言，翻译词条均以中文（简体）为准。

参与开发

请参阅开发指南。

API

外服适配

请参阅外服适配教程，对于国服已支持的功能，绝大部分的外服适配工作仅需要截图 + 简单的 JSON 修改即可。

Issue bot

请参阅 Issue Bot 使用方法

致谢

开源库

图像识别库：opencv
~~文字识别库：chineseocr_lite~~
文字识别库：PaddleOCR
深度学习部署库：FastDeploy
机器学习加速器：onnxruntime
~~关卡掉落识别：企鹅物流识别~~
地图格子识别：Arknights-Tile-Pos
C++ JSON 库：meojson
C++ 运算符解析器：calculator
~~C++ base64 编解码：cpp-base64~~
C++ 解压压缩库：zlib
C++ Gzip 封装：gzip-hpp
安卓触控事件器：Minitouch
安卓触控事件器：MaaTouch
WPF MVVM 框架：Stylet
WPF 控件库：HandyControl -> HandyControls
C# 日志：Serilog
C# JSON 库：Newtonsoft.Json & System.Text.Json
~~下载器：aria2~~

数据源

~~公开招募数据：明日方舟工具箱~~
~~干员及基建数据：PRTS Wiki~~
关卡数据：企鹅物流数据统计
游戏数据及资源：明日方舟客户端素材
游戏数据：《明日方舟》Yostar游戏数据

贡献/参与者

感谢所有参与到开发/测试中的朋友们，是大家的帮助让 MAA 越来越好！ (*´▽｀)ノノ

声明

本软件使用 GNU Affero General Public License v3.0 only 开源，并附带额外用户协议。
本软件 logo 并非使用 AGPL 3.0 协议开源，耗毛、vie 两位画师及软件全体开发者保留所有权利。不得以 AGPL 3.0 协议已授权为由在未经授权的情况下使用本软件 logo，不得在未经授权的情况下将本软件 logo 用于任何商业用途。
本软件开源、免费，仅供学习交流使用。若您遇到商家使用本软件进行代练并收费，可能是设备与时间等费用，产生的问题及后果与本软件无关。

DirectML 支持说明

本软件支持 GPU 加速功能，其在 Windows 平台上依赖于 Microsoft 提供的独立组件 DirectML。DirectML 并非本项目的开源部分，也不受 AGPL 3.0 的约束。为方便用户，我们随安装包附带了一个未经修改的 DirectML.dll 文件。如果您无需 GPU 加速功能，可安全删除该 DLL 文件，软件的核心功能仍可正常运行。

wled/WLED

Control WS2812B and many more types of digital RGB LEDs with an ESP32 over WiFi!

Welcome to WLED! ✨

A fast and feature-rich implementation of an ESP32 and ESP8266 webserver to control NeoPixel (WS2812B, WS2811, SK6812) LEDs or also SPI based chipsets like the WS2801 and APA102!

Originally created by Aircoookie

⚙️ Features

WS2812FX library with more than 100 special effects
FastLED noise effects and 50 palettes
Modern UI with color, effect and segment controls
Segments to set different effects and colors to user defined parts of the LED string
Settings page - configuration via the network
Access Point and station mode - automatic failsafe AP
Up to 10 LED outputs per instance
Support for RGBW strips
Up to 250 user presets to save and load colors/effects easily, supports cycling through them.
Presets can be used to automatically execute API calls
Nightlight function (gradually dims down)
Full OTA software updateability (HTTP + ArduinoOTA), password protectable
Configurable analog clock (Cronixie, 7-segment and EleksTube IPS clock support via usermods)
Configurable Auto Brightness limit for safe operation
Filesystem-based config for easier backup of presets and settings

💡 Supported light control interfaces

WLED app for Android and iOS
JSON and HTTP request APIs
MQTT
E1.31, Art-Net, DDP and TPM2.net
diyHue (Wled is supported by diyHue, including Hue Sync Entertainment under udp. Thanks to Gregory Mallios)
Hyperion
UDP realtime
Alexa voice control (including dimming and color)
Sync to Philips hue lights
Adalight (PC ambilight via serial) and TPM2
Sync color of multiple WLED devices (UDP notifier)
Infrared remotes (24-key RGB, receiver required)
Simple timers/schedules (time from NTP, timezones/DST supported)

📲 Quick start guide and documentation

See the documentation on our official site!

On this page you can find excellent tutorials and tools to help you get your new project up and running!

🖼️ User interface

💾 Compatible hardware

See here!

✌️ Other

Licensed under the EUPL v1.2 license
Credits here! CORS proxy by Corsfix

Join the Discord server to discuss everything about WLED!

Check out the WLED Discourse forum!

You can also send me mails to dev.aircoookie@gmail.com, but please, only do so if you want to talk to me privately.

If WLED really brightens up your day, you can

Disclaimer:

If you are prone to photosensitive epilepsy, we recommended you do not use this software.
If you still want to try, don't use strobe, lighting or noise modes or high effect speed settings.

As per the EUPL license, I assume no liability for any damage to you or any other person or equipment.

mozilla-ai/llamafile

Distribute and run LLMs with a single file.

llamafile

llamafile lets you distribute and run LLMs with a single file.

llamafile is a Mozilla Builders project (see its announcement blog post), now revamped by Mozilla.ai.

Our goal is to make open LLMs much more accessible to both developers and end users. We're doing that by combining llama.cpp with Cosmopolitan Libc into one framework that collapses all the complexity of LLMs down to a single-file executable (called a "llamafile") that runs locally on most operating systems and CPU archiectures, with no installation.

llamafile also includes whisperfile, a single-file speech-to-text tool built on whisper.cpp and the same Cosmopolitan packaging. It supports transcription and translation of audio files across all the same platforms, with no installation required.

v0.10.*

llamafile versions starting from 0.10.0 use a new build system, aimed at keeping our code more easily aligned with the latest versions of llama.cpp. This means they support more recent models and functionalities, but at the same time they might be missing some of the features you were accustomed to (check out this doc for a high-level description of what has been done). If you liked the "classic experience" more, you will always be able to access the previous versions from our releases page. Our pre-built llamafiles always show which version of the server they have been bundled with (0.9.* example, 0.10.* example), so you will always know which version of the software you are downloading.

We want to hear from you! Whether you are a new user or a long-time fan, please share what you find most valuable about llamafile and what would make it more useful for you. Read more via the blog and add your voice to the discussion here.

Quick Start

Download and run your first llamafile in minutes:

# Download an example model (Qwen3.5 0.8B)
curl -LO https://huggingface.co/mozilla-ai/llamafile_0.10/resolve/main/Qwen3.5-0.8B-Q8_0.llamafile

# Make it executable (macOS/Linux/BSD)
chmod +x Qwen3.5-0.8B-Q8_0.llamafile

# Run it
./Qwen3.5-0.8B-Q8_0.llamafile

We chose this model because that's the smallest one we have built a llamafile for, so most likely to work out-of-the-box for you. If you have powerful hardware and/or GPUs, feel free to choose larger and more expressive models which should provide more accurate responses.

Windows users: Rename the file to add .exe extension before running.

Note - Only executables under 4GB can run on Windows, so any llamafile above 4GB won't work. Download the llamafile binary and run it with any external weights/models(GGUF).

Documentation

Check the full documentation at docs.mozilla.ai/llamafile, or directly jump into one of the following subsections:

Licensing

While the llamafile project is Apache 2.0-licensed, our changes to llama.cpp and whisper.cpp are licensed under MIT (just like the projects themselves) so as to remain compatible and upstreamable in the future, should that be desired.

The llamafile logo on this page was generated with the assistance of DALL·E 3.

BruceDevices/firmware

Predatory ESP32 Firmware

🦈 Bruce

Bruce is a versatile ESP32 firmware that supports a ton of offensive features focusing on facilitating Red Team operations. It also supports M5stack and Lilygo products and works great with Cardputer, Sticks, M5Cores, T-Decks and T-Embeds.

Check our fully open-source hardware too: https://bruce.computer/boards

🏗️ How to install

The easiest way to install Bruce is using our official Web Flasher!

Check out: https://bruce.computer/flasher

Alternatively, you can download the latest binary from releases or actions and flash locally using esptool.py

esptool.py --port /dev/ttyACM0 write_flash 0x00000 Bruce-<device>.bin

For m5stack devices

If you already use M5Launcher to manage your m5stack device, you can install it with OTA

Or you can burn it directly from the m5burner tool, just search for 'Bruce' (My official builds will be uploaded by "owner" and have photos.) on the device category you want to and click on burn

⌨️ Discord Server

📑 Wiki

For more information on each function supported by Bruce, read our wiki here. Also, read our FAQ

💻 List of Features

WiFi

BLE

RF

RFID

IR

FM

NRF24

NRF24 Jammer
2.4G Spectrum
Mousejack

Scripts

JavaScript Interpreter Credits to justinknight93

Others

Clock

RTC Support
NTP time adjust
Manual adjust

Connect (ESPNOW)

Send File
Receive File
Send Commands
Receive Commands

Config

Specific functions per Device, the ones not mentioned here are available to all.

Device	CC1101	NRF24	FM Radio	PN532	Mic	BadUSB	RGB Led	Speaker	Fuel Guage	LITE_VERSION
M5Stack Cardputer (and ADV)	🆗	🆗	🆗	🆗	🆗	🆗	🆗	NS4168	❌	❌
M5Stack M5StickC PLUS2	🆗	🆗	🆗	🆗	🆗	🆗¹	❌	Tone	❌	❌
M5Stack M5StickC PLUS	🆗	🆗	🆗	🆗	🆗	🆗¹	❌	Tone	❌	❌²
M5Stack M5Core BASIC	🆗	🆗	🆗	🆗	🆗	🆗¹	❌	Tone	❌	❌
M5Stack M5Core2	🆗	🆗	🆗	🆗	🆗	🆗¹	❌	❌	❌	❌
M5Stack M5CoreS3/SE	🆗	🆗	🆗	🆗	❌	🆗	❌	❌	❌	❌
JCZN CYD‑2432S028	🆗	🆗	🆗	🆗	❌	🆗¹	❌	❌	❌	❌²
Lilygo T‑Embed CC1101	🆗	🆗	🆗	🆗	🆗	🆗	🆗	🆗	🆗	❌
Lilygo T‑Embed	🆗	🆗	🆗	🆗	🆗	🆗	🆗	🆗	❌	❌
Lilygo T-Display-S3	🆗	🆗	❌	❌	❌	🆗	❌	❌	❌	❌
Lilygo T‑Deck (and pro)	🆗	❌	❌	❌	❌	🆗	❌	❌	❌	❌
Lilygo T-Watch-S3	❌	❌	❌	❌	❌	🆗	❌	❌	❌	❌
Lilygo T-LoRa Pager	❌	❌	❌	❌	❌	🆗	❌	❌	❌	❌
Smoochiee V2	🆗	🆗	❌	🆗	❌	🆗	❌	❌	❌	❌
ESP32-C5	🆗	🆗	❌	🆗	❌	❌	❌	❌	❌	❌
Bruce RF Reaper	🆗	🆗	❌	❌ but w/ ST25R3916	❌	🆗	🆗	❌	🆗	❌

² CYD have a LITE_VERSION version for Launcher Compatibility ¹ Core, CYD and StickCs Bad-USB: here

LITE_VERSION: TelNet, SSH, WireGuard, ScanHosts, RawSniffer, Brucegotchi, BLEBacon, BLEScan and Interpreter are NOT available for M5Launcher Compatibility

✨ Why and how does it look?

Bruce stems from a keen observation within the community focused on devices like Flipper Zero. While these devices offered a glimpse into the world of offensive security, there was a palpable sense that something more could be achieved without being that overpriced, particularly with the robust and modular hardware ecosystem provided by ESP32 Devices, Lilygo and M5Stack products.

Other media can be found here.

👏 Acknowledgements

@bmorcelli for new core and a bunch of new features, also porting to many devices!
@IncursioHack for adding RF and RFID modules features.
@Luidiblu for logo and UI design assistance.
@eadmaster for adding a lot of features.
@rennancockles for a lot of RFID code, refactoring and others features.
@7h30th3r0n3 refactoring and a lot of help with WiFi attacks.
@Tawank refactoring interpreter among many other things
@pablonymous new RF functions to read RAW Data
Smoochiee for Bruce PCB design.
TH3_KR4K3N for Stick cplus extender PCB design.
Everyone who contributed in some way to the project, thanks ❤️

🚧 Disclaimer

Bruce is a tool for cyber offensive and red team operations, distributed under the terms of the Affero General Public License (AGPL). It is intended for legal and authorized security testing purposes only. Use of this software for any malicious or unauthorized activities is strictly prohibited. By downloading, installing, or using Bruce, you agree to comply with all applicable laws and regulations. This software is provided free of charge, and we do not accept payments for copies or modifications. The developers of Bruce assume no liability for any misuse of the software. Use at your own risk.

meshtastic/firmware

The official firmware for Meshtastic, an open-source, off-grid mesh communication system.

Meshtastic Firmware

Website - Documentation

Overview

This repository contains the official device firmware for Meshtastic, an open-source LoRa mesh networking project designed for long-range, low-power communication without relying on internet or cellular infrastructure. The firmware supports various hardware platforms, including ESP32, nRF52, RP2040/RP2350, and Linux-based devices.

Meshtastic enables text messaging, location sharing, and telemetry over a decentralized mesh network, making it ideal for outdoor adventures, emergency preparedness, and remote operations.

Get Started

🔧 Building Instructions – Learn how to compile the firmware from source.
⚡ Flashing Instructions – Install or update the firmware on your device.

Join our community and help improve Meshtastic! 🚀

Stats

nlohmann/json

JSON for Modern C++

Design goals

There are myriads of JSON libraries out there, and each may even have its reason to exist. Our class had these design goals:

Intuitive syntax. In languages such as Python, JSON feels like a first-class data type. We used all the operator magic of modern C++ to achieve the same feeling in your code. Check out the examples below and you'll know what I mean.
Trivial integration. Our whole code consists of a single header file json.hpp. That's it. No library, no subproject, no dependencies, no complex build system. The class is written in vanilla C++11. All in all, everything should require no adjustment of your compiler flags or project settings. The library is also included in all popular package managers.
Serious testing. Our code is heavily unit-tested and covers 100% of the code, including all exceptional behavior. Furthermore, we checked with Valgrind and the Clang Sanitizers that there are no memory leaks. Google OSS-Fuzz additionally runs fuzz tests against all parsers 24/7, effectively executing billions of tests so far. To maintain high quality, the project is following the Core Infrastructure Initiative (CII) best practices. See the quality assurance overview documentation.

Other aspects were not so important to us:

Memory efficiency. Each JSON object has an overhead of one pointer (the maximal size of a union) and one enumeration element (1 byte). The default generalization uses the following C++ data types: std::string for strings, int64_t, uint64_t or double for numbers, std::map for objects, std::vector for arrays, and bool for Booleans. However, you can template the generalized class basic_json to your needs.
Speed. There are certainly faster JSON libraries out there. However, if your goal is to speed up your development by adding JSON support with a single header, then this library is the way to go. If you know how to use a std::vector or std::map, you are already set.

See the contribution guidelines for more information.

Support

❓ If you have a question, please check if it is already answered in the FAQ or the Q&A section. If not, please ask a new question there.

📚 If you want to learn more about how to use the library, check out the rest of the README, have a look at code examples, or browse through the help pages.

🚧 If you want to understand the API better, check out the API Reference or have a look at the quick reference below.

🐛 If you found a bug, please check the FAQ if it is a known issue or the result of a design decision. Please also have a look at the issue list before you create a new issue. Please provide as much information as possible to help us understand and reproduce your issue.

There is also a docset for the documentation browsers Dash, Velocity, and Zeal that contains the full documentation as an offline resource.

Quick reference

Constructors basic_json, array, binary, object
Object inspection: type, operator value_t, type_name, is_primitive, is_structured, is_null, is_boolean, is_number, is_number_integer, is_number_unsigned, is_number_float, is_object, is_array, is_string, is_binary, is_discarded
Value access; get, get_to, get_ptr, get_ref, operator ValueType, get_binary
Element access: at, operator[], value, front, back
Lookup: find, count, contains
Iterators: begin, cbegin, end, cend, rbegin, rend, crbegin, crend, items
Capacity: empty, size, max_size
Modifiers: clear, push_back, operator+=, emplace_back, emplace, erase, insert, update, swap
Lexicographical comparison operators: operator==, operator!=, operator<, operator>, operator<=, operator>=, operator<=>
Serialization / Dumping: dump
Deserialization / Parsing: parse, accept, sax_parse
JSON Pointer functions: flatten, unflatten
JSON Patch functions: patch, patch_inplace, diff, merge_patch
Static functions: meta, get_allocator
Binary formats: from_bjdata, from_bson, from_cbor, from_msgpack, from_ubjson, to_bjdata, to_bson, to_cbor, to_msgpack, to_ubjson
Non-member functions: operator<<, operator>>, to_string
Literals: operator""_json
Helper classes: std::hash<basic_json>, std::swap<basic_json>

Full API documentation

Examples

Here are some examples to give you an idea how to use the class.

Besides the examples below, you may want to:

→ Check the documentation
→ Browse the standalone example files
→ Read the full API Documentation with self-contained examples for every function

Read JSON from a file

The json class provides an API for manipulating a JSON value. To create a json object by reading a JSON file:

#include <fstream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;

// ...

std::ifstream f("example.json");
json data = json::parse(f);

If using modules (enabled with NLOHMANN_JSON_BUILD_MODULES), this example becomes:

import std;
import nlohmann.json;

using json = nlohmann::json;

// ...

std::ifstream f("example.json");
json data = json::parse(f);

Creating `json` objects from JSON literals

Assume you want to hard-code this literal JSON value as a json object:

{
  "pi": 3.141,
  "happy": true
}

There are various options:

// Using (raw) string literals and json::parse
json ex1 = json::parse(R"(
  {
    "pi": 3.141,
    "happy": true
  }
)");

// Using user-defined (raw) string literals
using namespace nlohmann::literals;
json ex2 = R"(
  {
    "pi": 3.141,
    "happy": true
  }
)"_json;

// Using initializer lists
json ex3 = {
  {"happy", true},
  {"pi", 3.141},
};

JSON as a first-class data type

Here are some examples to give you an idea how to use the class.

Assume you want to create the JSON object

{
  "pi": 3.141,
  "happy": true,
  "name": "Niels",
  "nothing": null,
  "answer": {
    "everything": 42
  },
  "list": [1, 0, 2],
  "object": {
    "currency": "USD",
    "value": 42.99
  }
}

With this library, you could write:

// create an empty structure (null)
json j;

// add a number stored as double (note the implicit conversion of j to an object)
j["pi"] = 3.141;

// add a Boolean stored as bool
j["happy"] = true;

// add a string stored as std::string
j["name"] = "Niels";

// add another null object by passing nullptr
j["nothing"] = nullptr;

// add an object inside the object
j["answer"]["everything"] = 42;

// add an array stored as std::vector (using an initializer list)
j["list"] = { 1, 0, 2 };

// add another object (using an initializer list of pairs)
j["object"] = { {"currency", "USD"}, {"value", 42.99} };

// instead, you could also write (which looks very similar to the JSON above)
json j2 = {
  {"pi", 3.141},
  {"happy", true},
  {"name", "Niels"},
  {"nothing", nullptr},
  {"answer", {
    {"everything", 42}
  }},
  {"list", {1, 0, 2}},
  {"object", {
    {"currency", "USD"},
    {"value", 42.99}
  }}
};

Note that in all these cases, you never need to "tell" the compiler which JSON value type you want to use. If you want to be explicit or express some edge cases, the functions json::array() and json::object() will help:

// a way to express the empty array []
json empty_array_explicit = json::array();

// ways to express the empty object {}
json empty_object_implicit = json({});
json empty_object_explicit = json::object();

// a way to express an _array_ of key/value pairs [["currency", "USD"], ["value", 42.99]]
json array_not_object = json::array({ {"currency", "USD"}, {"value", 42.99} });

Serialization / Deserialization

To/from strings

You can create a JSON value (deserialization) by appending _json to a string literal:

// create object from string literal
json j = "{ \"happy\": true, \"pi\": 3.141 }"_json;

// or even nicer with a raw string literal
auto j2 = R"(
  {
    "happy": true,
    "pi": 3.141
  }
)"_json;

Note that without appending the _json suffix, the passed string literal is not parsed, but just used as JSON string value. That is, json j = "{ \"happy\": true, \"pi\": 3.141 }" would just store the string "{ "happy": true, "pi": 3.141 }" rather than parsing the actual object.

The string literal should be brought into scope with using namespace nlohmann::literals; (see json::parse()).

The above example can also be expressed explicitly using json::parse():

// parse explicitly
auto j3 = json::parse(R"({"happy": true, "pi": 3.141})");

You can also get a string representation of a JSON value (serialize):

// explicit conversion to string
std::string s = j.dump();    // {"happy":true,"pi":3.141}

// serialization with pretty printing
// pass in the amount of spaces to indent
std::cout << j.dump(4) << std::endl;
// {
//     "happy": true,
//     "pi": 3.141
// }

Note the difference between serialization and assignment:

// store a string in a JSON value
json j_string = "this is a string";

// retrieve the string value
auto cpp_string = j_string.get<std::string>();
// retrieve the string value (alternative when a variable already exists)
std::string cpp_string2;
j_string.get_to(cpp_string2);

// retrieve the serialized value (explicit JSON serialization)
std::string serialized_string = j_string.dump();

// output of original string
std::cout << cpp_string << " == " << cpp_string2 << " == " << j_string.get<std::string>() << '\n';
// output of serialized value
std::cout << j_string << " == " << serialized_string << std::endl;

.dump() returns the originally stored string value.

Note the library only supports UTF-8. When you store strings with different encodings in the library, calling dump() may throw an exception unless json::error_handler_t::replace or json::error_handler_t::ignore are used as error handlers.

To/from streams (e.g., files, string streams)

You can also use streams to serialize and deserialize:

// deserialize from standard input
json j;
std::cin >> j;

// serialize to standard output
std::cout << j;

// the setw manipulator was overloaded to set the indentation for pretty printing
std::cout << std::setw(4) << j << std::endl;

These operators work for any subclasses of std::istream or std::ostream. Here is the same example with files:

// read a JSON file
std::ifstream i("file.json");
json j;
i >> j;

// write prettified JSON to another file
std::ofstream o("pretty.json");
o << std::setw(4) << j << std::endl;

Please note that setting the exception bit for failbit is inappropriate for this use case. It will result in program termination due to the noexcept specifier in use.

Read from iterator range

You can also parse JSON from an iterator range; that is, from any container accessible by iterators whose value_type is an integral type of 1, 2, or 4 bytes, which will be interpreted as UTF-8, UTF-16, and UTF-32 respectively. For instance, a std::vector<std::uint8_t>, or a std::list<std::uint16_t>:

std::vector<std::uint8_t> v = {'t', 'r', 'u', 'e'};
json j = json::parse(v.begin(), v.end());

You may leave the iterators for the range [begin, end):

std::vector<std::uint8_t> v = {'t', 'r', 'u', 'e'};
json j = json::parse(v);

Custom data source

Since the parse function accepts arbitrary iterator ranges, you can provide your own data sources by implementing the LegacyInputIterator concept.

struct MyContainer {
  void advance();
  const char& get_current();
};

struct MyIterator {
    using difference_type = std::ptrdiff_t;
    using value_type = char;
    using pointer = const char*;
    using reference = const char&;
    using iterator_category = std::input_iterator_tag;

    MyIterator& operator++() {
        target->advance();
        return *this;
    }

    bool operator!=(const MyIterator& rhs) const {
        return rhs.target != target;
    }

    reference operator*() const {
        return target->get_current();
    }

    MyContainer* target = nullptr;
};

MyIterator begin(MyContainer& tgt) {
    return MyIterator{&tgt};
}

MyIterator end(const MyContainer&) {
    return {};
}

void foo() {
    MyContainer c;
    json j = json::parse(c);
}

SAX interface

The library uses a SAX-like interface with the following functions:

// called when null is parsed
bool null();

// called when a boolean is parsed; value is passed
bool boolean(bool val);

// called when a signed or unsigned integer number is parsed; value is passed
bool number_integer(number_integer_t val);
bool number_unsigned(number_unsigned_t val);

// called when a floating-point number is parsed; value and original string is passed
bool number_float(number_float_t val, const string_t& s);

// called when a string is parsed; value is passed and can be safely moved away
bool string(string_t& val);
// called when a binary value is parsed; value is passed and can be safely moved away
bool binary(binary_t& val);

// called when an object or array begins or ends, resp. The number of elements is passed (or -1 if not known)
bool start_object(std::size_t elements);
bool end_object();
bool start_array(std::size_t elements);
bool end_array();
// called when an object key is parsed; value is passed and can be safely moved away
bool key(string_t& val);

// called when a parse error occurs; byte position, the last token, and an exception is passed
bool parse_error(std::size_t position, const std::string& last_token, const detail::exception& ex);

The return value of each function determines whether parsing should proceed.

To implement your own SAX handler, proceed as follows:

Implement the SAX interface in a class. You can use class nlohmann::json_sax<json> as base class, but you can also use any class where the functions described above are implemented and public.
Create an object of your SAX interface class, e.g. my_sax.
Call bool json::sax_parse(input, &my_sax); where the first parameter can be any input like a string or an input stream and the second parameter is a pointer to your SAX interface.

Note the sax_parse function only returns a bool indicating the result of the last executed SAX event. It does not return a json value - it is up to you to decide what to do with the SAX events. Furthermore, no exceptions are thrown in case of a parse error -- it is up to you what to do with the exception object passed to your parse_error implementation. Internally, the SAX interface is used for the DOM parser (class json_sax_dom_parser) as well as the acceptor (json_sax_acceptor), see file json_sax.hpp.

STL-like access

We designed the JSON class to behave just like an STL container. In fact, it satisfies the ReversibleContainer requirement.

// create an array using push_back
json j;
j.push_back("foo");
j.push_back(1);
j.push_back(true);

// also use emplace_back
j.emplace_back(1.78);

// iterate the array
for (json::iterator it = j.begin(); it != j.end(); ++it) {
  std::cout << *it << '\n';
}

// range-based for
for (auto& element : j) {
  std::cout << element << '\n';
}

// getter/setter
const auto tmp = j[0].get<std::string>();
j[1] = 42;
bool foo = j.at(2);

// comparison
j == R"(["foo", 1, true, 1.78])"_json;  // true

// other stuff
j.size();     // 4 entries
j.empty();    // false
j.type();     // json::value_t::array
j.clear();    // the array is empty again

// convenience type checkers
j.is_null();
j.is_boolean();
j.is_number();
j.is_object();
j.is_array();
j.is_string();

// create an object
json o;
o["foo"] = 23;
o["bar"] = false;
o["baz"] = 3.141;

// also use emplace
o.emplace("weather", "sunny");

// special iterator member functions for objects
for (json::iterator it = o.begin(); it != o.end(); ++it) {
  std::cout << it.key() << " : " << it.value() << "\n";
}

// the same code as range for
for (auto& el : o.items()) {
  std::cout << el.key() << " : " << el.value() << "\n";
}

// even easier with structured bindings (C++17)
for (auto& [key, value] : o.items()) {
  std::cout << key << " : " << value << "\n";
}

// find an entry
if (o.contains("foo")) {
  // there is an entry with key "foo"
}

// or via find and an iterator
if (o.find("foo") != o.end()) {
  // there is an entry with key "foo"
}

// or simpler using count()
int foo_present = o.count("foo"); // 1
int fob_present = o.count("fob"); // 0

// delete an entry
o.erase("foo");

Conversion from STL containers

Any sequence container (std::array, std::vector, std::deque, std::forward_list, std::list) whose values can be used to construct JSON values (e.g., integers, floating point numbers, Booleans, string types, or again STL containers described in this section) can be used to create a JSON array. The same holds for similar associative containers (std::set, std::multiset, std::unordered_set, std::unordered_multiset), but in these cases the order of the elements of the array depends on how the elements are ordered in the respective STL container.

std::vector<int> c_vector {1, 2, 3, 4};
json j_vec(c_vector);
// [1, 2, 3, 4]

std::deque<double> c_deque {1.2, 2.3, 3.4, 5.6};
json j_deque(c_deque);
// [1.2, 2.3, 3.4, 5.6]

std::list<bool> c_list {true, true, false, true};
json j_list(c_list);
// [true, true, false, true]

std::forward_list<int64_t> c_flist {12345678909876, 23456789098765, 34567890987654, 45678909876543};
json j_flist(c_flist);
// [12345678909876, 23456789098765, 34567890987654, 45678909876543]

std::array<unsigned long, 4> c_array {{1, 2, 3, 4}};
json j_array(c_array);
// [1, 2, 3, 4]

std::set<std::string> c_set {"one", "two", "three", "four", "one"};
json j_set(c_set); // only one entry for "one" is used
// ["four", "one", "three", "two"]

std::unordered_set<std::string> c_uset {"one", "two", "three", "four", "one"};
json j_uset(c_uset); // only one entry for "one" is used
// maybe ["two", "three", "four", "one"]

std::multiset<std::string> c_mset {"one", "two", "one", "four"};
json j_mset(c_mset); // both entries for "one" are used
// maybe ["one", "two", "one", "four"]

std::unordered_multiset<std::string> c_umset {"one", "two", "one", "four"};
json j_umset(c_umset); // both entries for "one" are used
// maybe ["one", "two", "one", "four"]

Likewise, any associative key-value containers (std::map, std::multimap, std::unordered_map, std::unordered_multimap) whose keys can construct an std::string and whose values can be used to construct JSON values (see examples above) can be used to create a JSON object. Note that in case of multimaps, only one key is used in the JSON object and the value depends on the internal order of the STL container.

std::map<std::string, int> c_map { {"one", 1}, {"two", 2}, {"three", 3} };
json j_map(c_map);
// {"one": 1, "three": 3, "two": 2 }

std::unordered_map<const char*, double> c_umap { {"one", 1.2}, {"two", 2.3}, {"three", 3.4} };
json j_umap(c_umap);
// {"one": 1.2, "two": 2.3, "three": 3.4}

std::multimap<std::string, bool> c_mmap { {"one", true}, {"two", true}, {"three", false}, {"three", true} };
json j_mmap(c_mmap); // only one entry for key "three" is used
// maybe {"one": true, "two": true, "three": true}

std::unordered_multimap<std::string, bool> c_ummap { {"one", true}, {"two", true}, {"three", false}, {"three", true} };
json j_ummap(c_ummap); // only one entry for key "three" is used
// maybe {"one": true, "two": true, "three": true}

JSON Pointer and JSON Patch

The library supports JSON Pointer (RFC 6901) as an alternative means to address structured values. On top of this, JSON Patch (RFC 6902) allows describing differences between two JSON values -- effectively allowing patch and diff operations known from Unix.

// a JSON value
json j_original = R"({
  "baz": ["one", "two", "three"],
  "foo": "bar"
})"_json;

// access members with a JSON pointer (RFC 6901)
j_original["/baz/1"_json_pointer];
// "two"

// a JSON patch (RFC 6902)
json j_patch = R"([
  { "op": "replace", "path": "/baz", "value": "boo" },
  { "op": "add", "path": "/hello", "value": ["world"] },
  { "op": "remove", "path": "/foo"}
])"_json;

// apply the patch
json j_result = j_original.patch(j_patch);
// {
//    "baz": "boo",
//    "hello": ["world"]
// }

// calculate a JSON patch from two JSON values
json::diff(j_result, j_original);
// [
//   { "op":" replace", "path": "/baz", "value": ["one", "two", "three"] },
//   { "op": "remove","path": "/hello" },
//   { "op": "add", "path": "/foo", "value": "bar" }
// ]

JSON Merge Patch

The library supports JSON Merge Patch (RFC 7386) as a patch format. Instead of using JSON Pointer (see above) to specify values to be manipulated, it describes the changes using a syntax that closely mimics the document being modified.

// a JSON value
json j_document = R"({
  "a": "b",
  "c": {
    "d": "e",
    "f": "g"
  }
})"_json;

// a patch
json j_patch = R"({
  "a":"z",
  "c": {
    "f": null
  }
})"_json;

// apply the patch
j_document.merge_patch(j_patch);
// {
//  "a": "z",
//  "c": {
//    "d": "e"
//  }
// }

Implicit conversions

Supported types can be implicitly converted to JSON values.

It is recommended to NOT USE implicit conversions FROM a JSON value. You can find more details about this recommendation here. You can switch off implicit conversions by defining JSON_USE_IMPLICIT_CONVERSIONS to 0 before including the json.hpp header. When using CMake, you can also achieve this by setting the option JSON_ImplicitConversions to OFF.

// strings
std::string s1 = "Hello, world!";
json js = s1;
auto s2 = js.get<std::string>();
// NOT RECOMMENDED
std::string s3 = js;
std::string s4;
s4 = js;

// Booleans
bool b1 = true;
json jb = b1;
auto b2 = jb.get<bool>();
// NOT RECOMMENDED
bool b3 = jb;
bool b4;
b4 = jb;

// numbers
int i = 42;
json jn = i;
auto f = jn.get<double>();
// NOT RECOMMENDED
double f2 = jb;
double f3;
f3 = jb;

// etc.

Note that char types are not automatically converted to JSON strings, but to integer numbers. A conversion to a string must be specified explicitly:

char ch = 'A';                       // ASCII value 65
json j_default = ch;                 // stores integer number 65
json j_string = std::string(1, ch);  // stores string "A"

Arbitrary types conversions

Every type can be serialized in JSON, not just STL containers and scalar types. Usually, you would do something along those lines:

namespace ns {
    // a simple struct to model a person
    struct person {
        std::string name;
        std::string address;
        int age;
    };
}

ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};

// convert to JSON: copy each value into the JSON object
json j;
j["name"] = p.name;
j["address"] = p.address;
j["age"] = p.age;

// ...

// convert from JSON: copy each value from the JSON object
ns::person p {
    j["name"].get<std::string>(),
    j["address"].get<std::string>(),
    j["age"].get<int>()
};

It works, but that's quite a lot of boilerplate... Fortunately, there's a better way:

// create a person
ns::person p {"Ned Flanders", "744 Evergreen Terrace", 60};

// conversion: person -> json
json j = p;

std::cout << j << std::endl;
// {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}

// conversion: json -> person
auto p2 = j.get<ns::person>();

// that's it
assert(p == p2);

Basic usage

To make this work with one of your types, you only need to provide two functions:

using json = nlohmann::json;

namespace ns {
    void to_json(json& j, const person& p) {
        j = json{{"name", p.name}, {"address", p.address}, {"age", p.age}};
    }

    void from_json(const json& j, person& p) {
        j.at("name").get_to(p.name);
        j.at("address").get_to(p.address);
        j.at("age").get_to(p.age);
    }
} // namespace ns

That's all! When calling the json constructor with your type, your custom to_json method will be automatically called. Likewise, when calling get<your_type>() or get_to(your_type&), the from_json method will be called.

Some important things:

Those methods MUST be in your type's namespace (which can be the global namespace), or the library will not be able to locate them (in this example, they are in namespace ns, where person is defined).
Those methods MUST be available (e.g., proper headers must be included) everywhere you use these conversions. Look at issue 1108 for errors that may occur otherwise.
When using get<your_type>(), your_type MUST be DefaultConstructible. (There is a way to bypass this requirement described later.)
In function from_json, use function at() to access the object values rather than operator[]. In case a key does not exist, at throws an exception that you can handle, whereas operator[] exhibits undefined behavior.
You do not need to add serializers or deserializers for STL types like std::vector: the library already implements these.

Simplify your life with macros

If you just want to serialize/deserialize some structs, the to_json/from_json functions can be a lot of boilerplate. There are several macros to make your life easier as long as you want to use a JSON object as serialization.

Which macro to choose depends on whether private member variables need to be accessed, a deserialization is needed, missing values should yield an error or should be replaced by default values, and if derived classes are used. See this overview to choose the right one for your use case.

Example usage of macros

The to_json/from_json functions for the person struct above can be created with NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE. In all macros, the first parameter is the name of the class/struct, and all remaining parameters name the members.

namespace ns {
    NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(person, name, address, age)
}

If you want to inherit the person struct and add a field to it, it can be done with:

namespace ns {
    struct person_derived : person {
        std::string email;
    };
    
    NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE(person_derived, person, email)
}

Here is another example with private members, where NLOHMANN_DEFINE_TYPE_INTRUSIVE is needed:

namespace ns {
    class address {
      private:
        std::string street;
        int housenumber;
        int postcode;
  
      public:
        NLOHMANN_DEFINE_TYPE_INTRUSIVE(address, street, housenumber, postcode)
    };
}

Or in case if you use some naming convention that you do not want to expose to JSON:

namespace ns {
    class address {
      private:
        std::string m_street;
        int m_housenumber;
        int m_postcode;

      public:
        NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_NAMES(address, "street", m_street,
                                                           "housenumber", m_housenumber,
                                                           "postcode", m_postcode)
    };
}

How do I convert third-party types?

This requires a bit more advanced technique. But first, let's see how this conversion mechanism works:

The library uses JSON Serializers to convert types to JSON. The default serializer for nlohmann::json is nlohmann::adl_serializer (ADL means Argument-Dependent Lookup).

It is implemented like this (simplified):

template <typename T>
struct adl_serializer {
    static void to_json(json& j, const T& value) {
        // calls the "to_json" method in T's namespace
    }

    static void from_json(const json& j, T& value) {
        // same thing, but with the "from_json" method
    }
};

This serializer works fine when you have control over the type's namespace. However, what about boost::optional or std::filesystem::path (C++17)? Hijacking the boost namespace is pretty bad, and it's illegal to add something other than template specializations to std...

To solve this, you need to add a specialization of adl_serializer to the nlohmann namespace, here's an example:

// partial specialization (full specialization works too)
namespace nlohmann {
    template <typename T>
    struct adl_serializer<boost::optional<T>> {
        static void to_json(json& j, const boost::optional<T>& opt) {
            if (opt == boost::none) {
                j = nullptr;
            } else {
              j = *opt; // this will call adl_serializer<T>::to_json which will
                        // find the free function to_json in T's namespace!
            }
        }

        static void from_json(const json& j, boost::optional<T>& opt) {
            if (j.is_null()) {
                opt = boost::none;
            } else {
                opt = j.get<T>(); // same as above, but with
                                  // adl_serializer<T>::from_json
            }
        }
    };
}

How can I use `get()` for non-default constructible/non-copyable types?

There is a way if your type is MoveConstructible. You will need to specialize the adl_serializer as well, but with a special from_json overload:

struct move_only_type {
    move_only_type() = delete;
    move_only_type(int ii): i(ii) {}
    move_only_type(const move_only_type&) = delete;
    move_only_type(move_only_type&&) = default;

    int i;
};

namespace nlohmann {
    template <>
    struct adl_serializer<move_only_type> {
        // note: the return type is no longer 'void', and the method only takes
        // one argument
        static move_only_type from_json(const json& j) {
            return {j.get<int>()};
        }

        // Here's the catch! You must provide a to_json method! Otherwise, you
        // will not be able to convert move_only_type to json, since you fully
        // specialized adl_serializer on that type
        static void to_json(json& j, move_only_type t) {
            j = t.i;
        }
    };
}

Can I write my own serializer? (Advanced use)

Yes. You might want to take a look at unit-udt.cpp in the test suite, to see a few examples.

If you write your own serializer, you'll need to do a few things:

use a different basic_json alias than nlohmann::json (the last template parameter of basic_json is the JSONSerializer)
use your basic_json alias (or a template parameter) in all your to_json/from_json methods
use nlohmann::to_json and nlohmann::from_json when you need ADL

Here is an example, without simplifications, that only accepts types with a size <= 32, and uses ADL.

// You should use void as a second template argument
// if you don't need compile-time checks on T
template<typename T, typename SFINAE = typename std::enable_if<sizeof(T) <= 32>::type>
struct less_than_32_serializer {
    template <typename BasicJsonType>
    static void to_json(BasicJsonType& j, T value) {
        // we want to use ADL, and call the correct to_json overload
        using nlohmann::to_json; // this method is called by adl_serializer,
                                 // this is where the magic happens
        to_json(j, value);
    }

    template <typename BasicJsonType>
    static void from_json(const BasicJsonType& j, T& value) {
        // same thing here
        using nlohmann::from_json;
        from_json(j, value);
    }
};

Be very careful when reimplementing your serializer, you can stack overflow if you don't pay attention:

template <typename T, void>
struct bad_serializer
{
    template <typename BasicJsonType>
    static void to_json(BasicJsonType& j, const T& value) {
      // this calls BasicJsonType::json_serializer<T>::to_json(j, value)
      // if BasicJsonType::json_serializer == bad_serializer ... oops!
      j = value;
    }

    template <typename BasicJsonType>
    static void to_json(const BasicJsonType& j, T& value) {
      // this calls BasicJsonType::json_serializer<T>::from_json(j, value)
      // if BasicJsonType::json_serializer == bad_serializer ... oops!
      value = j.get<T>(); // oops!
    }
};

Specializing enum conversion

By default, enum values are serialized to JSON as integers. In some cases, this could result in undesired behavior. If an enum is modified or re-ordered after data has been serialized to JSON, the later deserialized JSON data may be undefined or a different enum value than was originally intended.

It is possible to more precisely specify how a given enum is mapped to and from JSON as shown below:

// example enum type declaration
enum TaskState {
    TS_STOPPED,
    TS_RUNNING,
    TS_COMPLETED,
    TS_INVALID=-1,
};

// map TaskState values to JSON as strings
NLOHMANN_JSON_SERIALIZE_ENUM( TaskState, {
    {TS_INVALID, nullptr},
    {TS_STOPPED, "stopped"},
    {TS_RUNNING, "running"},
    {TS_COMPLETED, "completed"},
})

The NLOHMANN_JSON_SERIALIZE_ENUM() macro declares a set of to_json() / from_json() functions for type TaskState while avoiding repetition and boilerplate serialization code.

Usage:

// enum to JSON as string
json j = TS_STOPPED;
assert(j == "stopped");

// json string to enum
json j3 = "running";
assert(j3.get<TaskState>() == TS_RUNNING);

// undefined json value to enum (where the first map entry above is the default)
json jPi = 3.14;
assert(jPi.get<TaskState>() == TS_INVALID);

Just as in Arbitrary Type Conversions above,

NLOHMANN_JSON_SERIALIZE_ENUM() MUST be declared in your enum type's namespace (which can be the global namespace), or the library will not be able to locate it, and it will default to integer serialization.
It MUST be available (e.g., proper headers must be included) everywhere you use the conversions.

Other Important points:

When using get<ENUM_TYPE>(), undefined JSON values will default to the first pair specified in your map. Select this default pair carefully.
If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the map will be returned when converting to or from JSON.

Binary formats (BSON, CBOR, MessagePack, UBJSON, and BJData)

Though JSON is a ubiquitous data format, it is not a very compact format suitable for data exchange, for instance over a network. Hence, the library supports BSON (Binary JSON), CBOR (Concise Binary Object Representation), MessagePack, UBJSON (Universal Binary JSON Specification) and BJData (Binary JData) to efficiently encode JSON values to byte vectors and to decode such vectors.

// create a JSON value
json j = R"({"compact": true, "schema": 0})"_json;

// serialize to BSON
std::vector<std::uint8_t> v_bson = json::to_bson(j);

// 0x1B, 0x00, 0x00, 0x00, 0x08, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0x00, 0x01, 0x10, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00

// roundtrip
json j_from_bson = json::from_bson(v_bson);

// serialize to CBOR
std::vector<std::uint8_t> v_cbor = json::to_cbor(j);

// 0xA2, 0x67, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0xF5, 0x66, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x00

// roundtrip
json j_from_cbor = json::from_cbor(v_cbor);

// serialize to MessagePack
std::vector<std::uint8_t> v_msgpack = json::to_msgpack(j);

// 0x82, 0xA7, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0xC3, 0xA6, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x00

// roundtrip
json j_from_msgpack = json::from_msgpack(v_msgpack);

// serialize to UBJSON
std::vector<std::uint8_t> v_ubjson = json::to_ubjson(j);

// 0x7B, 0x69, 0x07, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0x54, 0x69, 0x06, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x69, 0x00, 0x7D

// roundtrip
json j_from_ubjson = json::from_ubjson(v_ubjson);

The library also supports binary types from BSON, CBOR (byte strings), and MessagePack (bin, ext, fixext). They are stored by default as std::vector<std::uint8_t> to be processed outside the library.

// CBOR byte string with payload 0xCAFE
std::vector<std::uint8_t> v = {0x42, 0xCA, 0xFE};

// read value
json j = json::from_cbor(v);

// the JSON value has type binary
j.is_binary(); // true

// get reference to stored binary value
auto& binary = j.get_binary();

// the binary value has no subtype (CBOR has no binary subtypes)
binary.has_subtype(); // false

// access std::vector<std::uint8_t> member functions
binary.size(); // 2
binary[0]; // 0xCA
binary[1]; // 0xFE

// set subtype to 0x10
binary.set_subtype(0x10);

// serialize to MessagePack
auto cbor = json::to_msgpack(j); // 0xD5 (fixext2), 0x10, 0xCA, 0xFE

Customers

The library is used in multiple projects, applications, operating systems, etc. The list below is not exhaustive, but the result of an internet search. If you know further customers of the library, please let me know, see contact.

Supported compilers

Though it's 2026 already, the support for C++11 is still a bit sparse. Currently, the following compilers are known to work:

GCC 4.8 - 14.2 (and possibly later)
Clang 3.4 - 21.0 (and possibly later)
Apple Clang 9.1 - 16.0 (and possibly later)
Intel C++ Compiler 17.0.2 (and possibly later)
Nvidia CUDA Compiler 11.0.221 (and possibly later)
Microsoft Visual C++ 2015 / Build Tools 14.0.25123.0 (and possibly later)
Microsoft Visual C++ 2017 / Build Tools 15.5.180.51428 (and possibly later)
Microsoft Visual C++ 2019 / Build Tools 16.3.1+1def00d3d (and possibly later)
Microsoft Visual C++ 2022 / Build Tools 19.30.30709.0 (and possibly later)

I would be happy to learn about other compilers/versions.

Please note:

GCC 4.8 has a bug 57824: multiline raw strings cannot be the arguments to macros. Don't use multiline raw strings directly in macros with this compiler.
Android defaults to using very old compilers and C++ libraries. To fix this, add the following to your Application.mk. This will switch to the LLVM C++ library, the Clang compiler, and enable C++11 and other features disabled by default.
```
APP_STL := c++_shared
NDK_TOOLCHAIN_VERSION := clang3.6
APP_CPPFLAGS += -frtti -fexceptions
```
The code compiles successfully with Android NDK, Revision 9 - 11 (and possibly later) and CrystaX's Android NDK version 10.
For GCC running on MinGW or Android SDK, the error 'to_string' is not a member of 'std' (or similarly, for strtod or strtof) may occur. Note this is not an issue with the code, but rather with the compiler itself. On Android, see above to build with a newer environment. For MinGW, please refer to this site and this discussion for information on how to fix this bug. For Android NDK using APP_STL := gnustl_static, please refer to this discussion.
Unsupported versions of GCC and Clang are rejected by #error directives. This can be switched off by defining JSON_SKIP_UNSUPPORTED_COMPILER_CHECK. Note that you can expect no support in this case.

See the page quality assurance on the compilers used to check the library in the CI.

Integration

json.hpp is the single required file in single_include/nlohmann or released here. You need to add

#include <nlohmann/json.hpp>

// for convenience
using json = nlohmann::json;

to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., -std=c++11 for GCC and Clang).

You can further use file include/nlohmann/json_fwd.hpp for forward-declarations. The installation of json_fwd.hpp (as part of cmake's install step) can be achieved by setting -DJSON_MultipleHeaders=ON.

CMake

You can also use the nlohmann_json::nlohmann_json interface target in CMake. This target populates the appropriate usage requirements for INTERFACE_INCLUDE_DIRECTORIES to point to the appropriate include directories and INTERFACE_COMPILE_FEATURES for the necessary C++11 flags.

External

To use this library from a CMake project, you can locate it directly with find_package() and use the namespaced imported target from the generated package configuration:

# CMakeLists.txt
find_package(nlohmann_json 3.12.0 REQUIRED)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)

The package configuration file, nlohmann_jsonConfig.cmake, can be used either from an install tree or directly out of the build tree.

Embedded

To embed the library directly into an existing CMake project, place the entire source tree in a subdirectory and call add_subdirectory() in your CMakeLists.txt file:

# Typically you don't care so much for a third party library's tests to be
# run from your own project's code.
set(JSON_BuildTests OFF CACHE INTERNAL "")

# If you only include this third party in PRIVATE source files, you do not
# need to install it when your main project gets installed.
# set(JSON_Install OFF CACHE INTERNAL "")

# Don't use include(nlohmann_json/CMakeLists.txt) since that carries with it
# unintended consequences that will break the build.  It's generally
# discouraged (although not necessarily well documented as such) to use
# include(...) for pulling in other CMake projects anyways.
add_subdirectory(nlohmann_json)
...
add_library(foo ...)
...
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)

Embedded (FetchContent)

Since CMake v3.11, FetchContent can be used to automatically download a release as a dependency at configure time.

Example:

include(FetchContent)

FetchContent_Declare(json URL https://github.com/nlohmann/json/releases/download/v3.12.0/json.tar.xz)
FetchContent_MakeAvailable(json)

target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)

Note: It is recommended to use the URL approach described above, which is supported as of version 3.10.0. See https://json.nlohmann.me/integration/cmake/#fetchcontent for more information.

Supporting Both

To allow your project to support either an externally supplied or an embedded JSON library, you can use a pattern akin to the following:

# Top level CMakeLists.txt
project(FOO)
...
option(FOO_USE_EXTERNAL_JSON "Use an external JSON library" OFF)
...
add_subdirectory(thirdparty)
...
add_library(foo ...)
...
# Note that the namespaced target will always be available regardless of the
# import method
target_link_libraries(foo PRIVATE nlohmann_json::nlohmann_json)

# thirdparty/CMakeLists.txt
...
if(FOO_USE_EXTERNAL_JSON)
  find_package(nlohmann_json 3.12.0 REQUIRED)
else()
  set(JSON_BuildTests OFF CACHE INTERNAL "")
  add_subdirectory(nlohmann_json)
endif()
...

thirdparty/nlohmann_json is then a complete copy of this source tree.

Package Managers

Use your favorite package manager to use the library.

Homebrew nlohmann-json
Meson nlohmann_json
Bazel nlohmann_json
Conan nlohmann_json
Spack nlohmann-json
Hunter nlohmann_json
vcpkg nlohmann-json
cget nlohmann/json
Swift Package Manager nlohmann/json
Nuget nlohmann.json
Conda nlohmann_json
MacPorts nlohmann-json
cpm.cmake gh:nlohmann/json
xmake nlohmann_json

The library is part of many package managers. See the documentation for detailed descriptions and examples.

Pkg-config

If you are using bare Makefiles, you can use pkg-config to generate the include flags that point to where the library is installed:

pkg-config nlohmann_json --cflags

License

The class is licensed under the MIT License:

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The class contains a copy of Hedley from Evan Nemerson which is licensed as CC0-1.0.
The class contains parts of Google Abseil which is licensed under the Apache 2.0 License.

The library is compliant to version 3.3 of the REUSE specification:

Every source file contains an SPDX copyright header.
The full text of all licenses used in the repository can be found in the LICENSES folder.
File .reuse/dep5 contains an overview of all files' copyrights and licenses.
Run pipx run reuse lint to verify the project's REUSE compliance and pipx run reuse spdx to generate a SPDX SBOM.

Contact

If you have questions regarding the library, I would like to invite you to open an issue at GitHub. Please describe your request, problem, or question as detailed as possible, and also mention the version of the library you are using as well as the version of your compiler and operating system. Opening an issue at GitHub allows other users and contributors to this library to collaborate. For instance, I have little experience with MSVC, and most issues in this regard have been solved by a growing community. If you have a look at the closed issues, you will see that we react quite timely in most cases.

Only if your request would contain confidential information, please send me an email. For encrypted messages, please use this key.

Security

Commits by Niels Lohmann and releases are signed with this PGP Key.

Thanks

I deeply appreciate the help of the following people.

Teemperor implemented CMake support and lcov integration, realized escape and Unicode handling in the string parser, and fixed the JSON serialization.
elliotgoodrich fixed an issue with double deletion in the iterator classes.
kirkshoop made the iterators of the class composable to other libraries.
wancw fixed a bug that hindered the class to compile with Clang.
Tomas Åblad found a bug in the iterator implementation.
Joshua C. Randall fixed a bug in the floating-point serialization.
Aaron Burghardt implemented code to parse streams incrementally. Furthermore, he greatly improved the parser class by allowing the definition of a filter function to discard undesired elements while parsing.
Daniel Kopeček fixed a bug in the compilation with GCC 5.0.
Florian Weber fixed a bug in and improved the performance of the comparison operators.
Eric Cornelius pointed out a bug in the handling with NaN and infinity values. He also improved the performance of the string escaping.
易思龙 implemented a conversion from anonymous enums.
kepkin patiently pushed forward the support for Microsoft Visual Studio.
gregmarr simplified the implementation of reverse iterators and helped with numerous hints and improvements. In particular, he pushed forward the implementation of user-defined types.
Caio Luppi fixed a bug in the Unicode handling.
dariomt fixed some typos in the examples.
Daniel Frey cleaned up some pointers and implemented exception-safe memory allocation.
Colin Hirsch took care of a small namespace issue.
Huu Nguyen corrected a variable name in the documentation.
Silverweed overloaded parse() to accept an rvalue reference.
dariomt fixed a subtlety in MSVC type support and implemented the get_ref() function to get a reference to stored values.
ZahlGraf added a workaround that allows compilation using Android NDK.
whackashoe replaced a function that was marked as unsafe by Visual Studio.
406345 fixed two small warnings.
Glen Fernandes noted a potential portability problem in the has_mapped_type function.
Corbin Hughes fixed some typos in the contribution guidelines.
twelsby fixed the array subscript operator, an issue that failed the MSVC build, and floating-point parsing/dumping. He further added support for unsigned integer numbers and implemented better roundtrip support for parsed numbers.
Volker Diels-Grabsch fixed a link in the README file.
msm- added support for American Fuzzy Lop.
Annihil fixed an example in the README file.
Themercee noted a wrong URL in the README file.
Lv Zheng fixed a namespace issue with int64_t and uint64_t.
abc100m analyzed the issues with GCC 4.8 and proposed a partial solution.
zewt added useful notes to the README file about Android.
Róbert Márki added a fix to use move iterators and improved the integration via CMake.
Chris Kitching cleaned up the CMake files.
Tom Needham fixed a subtle bug with MSVC 2015 which was also proposed by Michael K..
Mário Feroldi fixed a small typo.
duncanwerner found a really embarrassing performance regression in the 2.0.0 release.
Damien fixed one of the last conversion warnings.
Thomas Braun fixed a warning in a test case and adjusted MSVC calls in the CI.
Théo DELRIEU patiently and constructively oversaw the long way toward iterator-range parsing. He also implemented the magic behind the serialization/deserialization of user-defined types and split the single header file into smaller chunks.
Stefan fixed a minor issue in the documentation.
Vasil Dimov fixed the documentation regarding conversions from std::multiset.
ChristophJud overworked the CMake files to ease project inclusion.
Vladimir Petrigo made a SFINAE hack more readable and added Visual Studio 17 to the build matrix.
Denis Andrejew fixed a grammar issue in the README file.
Pierre-Antoine Lacaze found a subtle bug in the dump() function.
TurpentineDistillery pointed to std::locale::classic() to avoid too much locale joggling, found some nice performance improvements in the parser, improved the benchmarking code, and realized locale-independent number parsing and printing.
cgzones had an idea how to fix the Coverity scan.
Jared Grubb silenced a nasty documentation warning.
Yixin Zhang fixed an integer overflow check.
Bosswestfalen merged two iterator classes into a smaller one.
Daniel599 helped to get Travis to execute the tests with Clang's sanitizers.
Jonathan Lee fixed an example in the README file.
gnzlbg supported the implementation of user-defined types.
Alexej Harm helped to get the user-defined types working with Visual Studio.
Jared Grubb supported the implementation of user-defined types.
EnricoBilla noted a typo in an example.
Martin Hořeňovský found a way for a 2x speedup for the compilation time of the test suite.
ukhegg found proposed an improvement for the examples section.
rswanson-ihi noted a typo in the README.
Mihai Stan fixed a bug in the comparison with nullptrs.
Tushar Maheshwari added cotire support to speed up the compilation.
TedLyngmo noted a typo in the README, removed unnecessary bit arithmetic, and fixed some -Weffc++ warnings.
Krzysztof Woś made exceptions more visible.
ftillier fixed a compiler warning.
tinloaf made sure all pushed warnings are properly popped.
Fytch found a bug in the documentation.
Jay Sistar implemented a Meson build description.
Henry Lee fixed a warning in ICC and improved the iterator implementation.
Vincent Thiery maintains a package for the Conan package manager.
Steffen fixed a potential issue with MSVC and std::min.
Mike Tzou fixed some typos.
amrcode noted misleading documentation about comparison of floats.
Oleg Endo reduced the memory consumption by replacing <iostream> with <iosfwd>.
dan-42 cleaned up the CMake files to simplify including/reusing of the library.
Nikita Ofitserov allowed for moving values from initializer lists.
Greg Hurrell fixed a typo.
Dmitry Kukovinets fixed a typo.
kbthomp1 fixed an issue related to the Intel OSX compiler.
Markus Werle fixed a typo.
WebProdPP fixed a subtle error in a precondition check.
Alex noted an error in a code sample.
Tom de Geus reported some warnings with ICC and helped to fix them.
Perry Kundert simplified reading from input streams.
Sonu Lohani fixed a small compilation error.
Jamie Seward fixed all MSVC warnings.
Nate Vargas added a Doxygen tag file.
pvleuven helped to fix a warning in ICC.
Pavel helped to fix some warnings in MSVC.
Jamie Seward avoided unnecessary string copies in find() and count().
Mitja fixed some typos.
Jorrit Wronski updated the Hunter package links.
Matthias Möller added a .natvis for the MSVC debug view.
bogemic fixed some C++17 deprecation warnings.
Eren Okka fixed some MSVC warnings.
abolz integrated the Grisu2 algorithm for proper floating-point formatting, allowing more roundtrip checks to succeed.
Vadim Evard fixed a Markdown issue in the README.
zerodefect fixed a compiler warning.
Kert allowed to template the string type in the serialization and added the possibility to override the exceptional behavior.
mark-99 helped fix an ICC error.
Patrik Huber fixed links in the README file.
johnfb found a bug in the implementation of CBOR's indefinite length strings.
Paul Fultz II added a note on the cget package manager.
Wilson Lin made the integration section of the README more concise.
RalfBielig detected and fixed a memory leak in the parser callback.
agrianius allowed dumping JSON to an alternative string type.
Kevin Tonon overworked the C++11 compiler checks in CMake.
Axel Huebl simplified a CMake check and added support for the Spack package manager.
Carlos O'Ryan fixed a typo.
James Upjohn fixed a version number in the compilers section.
Chuck Atkins adjusted the CMake files to the CMake packaging guidelines and provided documentation for the CMake integration.
Jan Schöppach fixed a typo.
martin-mfg fixed a typo.
Matthias Möller removed the dependency from std::stringstream.
agrianius added code to use alternative string implementations.
Daniel599 allowed to use more algorithms with the items() function.
Julius Rakow fixed the Meson include directory and fixed the links to cppreference.com.
Sonu Lohani fixed the compilation with MSVC 2015 in debug mode.
grembo fixed the test suite and re-enabled several test cases.
Hyeon Kim introduced the macro JSON_INTERNAL_CATCH to control the exception handling inside the library.
thyu fixed a compiler warning.
David Guthrie fixed a subtle compilation error with Clang 3.4.2.
Dennis Fischer allowed to call find_package without installing the library.
Hyeon Kim fixed an issue with a double macro definition.
Ben Berman made some error messages more understandable.
zakalibit fixed a compilation problem with the Intel C++ compiler.
mandreyel fixed a compilation problem.
Kostiantyn Ponomarenko added version and license information to the Meson build file.
Henry Schreiner added support for GCC 4.8.
knilch made sure the test suite does not stall when run in the wrong directory.
Antonio Borondo fixed an MSVC 2017 warning.
Dan Gendreau implemented the NLOHMANN_JSON_SERIALIZE_ENUM macro to quickly define an enum/JSON mapping.
efp added line and column information to parse errors.
julian-becker added BSON support.
Pratik Chowdhury added support for structured bindings.
David Avedissian added support for Clang 5.0.1 (PS4 version).
Jonathan Dumaresq implemented an input adapter to read from FILE*.
kjpus fixed a link in the documentation.
Manvendra Singh fixed a typo in the documentation.
ziggurat29 fixed an MSVC warning.
Sylvain Corlay added code to avoid an issue with MSVC.
mefyl fixed a bug when JSON was parsed from an input stream.
Millian Poquet allowed to install the library via Meson.
Michael Behrns-Miller found an issue with a missing namespace.
Nasztanovics Ferenc fixed a compilation issue with libc 2.12.
Andreas Schwab fixed the endian conversion.
Mark-Dunning fixed a warning in MSVC.
Gareth Sylvester-Bradley added operator/ for JSON Pointers.
John-Mark noted a missing header.
Vitaly Zaitsev fixed compilation with GCC 9.0.
Laurent Stacul fixed compilation with GCC 9.0.
Ivor Wanders helped to reduce the CMake requirement to version 3.1.
njlr updated the Buckaroo instructions.
Lion fixed a compilation issue with GCC 7 on CentOS.
Isaac Nickaein improved the integer serialization performance and implemented the contains() function.
past-due suppressed an unfixable warning.
Elvis Oric improved Meson support.
Matěj Plch fixed an example in the README.
Mark Beckwith fixed a typo.
scinart fixed a bug in the serializer.
Patrick Boettcher implemented push_back() and pop_back() for JSON Pointers.
Bruno Oliveira added support for Conda.
Michele Caini fixed links in the README.
Hani documented how to install the library with NuGet.
Mark Beckwith fixed a typo.
yann-morin-1998 helped to reduce the CMake requirement to version 3.1.
Konstantin Podsvirov maintains a package for the MSYS2 software distro.
remyabel added GNUInstallDirs to the CMake files.
Taylor Howard fixed a unit test.
Gabe Ron implemented the to_string method.
Watal M. Iwasaki fixed a Clang warning.
Viktor Kirilov switched the unit tests from Catch to doctest
Juncheng E fixed a typo.
tete17 fixed a bug in the contains function.
Xav83 fixed some cppcheck warnings.
0xflotus fixed some typos.
Christian Deneke added a const version of json_pointer::back.
Julien Hamaide made the items() function work with custom string types.
Evan Nemerson updated fixed a bug in Hedley and updated this library accordingly.
Florian Pigorsch fixed a lot of typos.
Camille Bégué fixed an issue in the conversion from std::pair and std::tuple to json.
Anthony VH fixed a compile error in an enum deserialization.
Yuriy Vountesmery noted a subtle bug in a preprocessor check.
Chen fixed numerous issues in the library.
Antony Kellermann added a CI step for GCC 10.1.
Alex fixed an MSVC warning.
Rainer proposed an improvement in the floating-point serialization in CBOR.
Francois Chabot made performance improvements in the input adapters.
Arthur Sonzogni documented how the library can be included via FetchContent.
Rimas Misevičius fixed an error message.
Alexander Myasnikov fixed some examples and a link in the README.
Hubert Chathi made CMake's version config file architecture-independent.
OmnipotentEntity implemented the binary values for CBOR, MessagePack, BSON, and UBJSON.
ArtemSarmini fixed a compilation issue with GCC 10 and fixed a leak.
Evgenii Sopov integrated the library to the wsjcpp package manager.
Sergey Linev fixed a compiler warning.
Miguel Magalhães fixed the year in the copyright.
Gareth Sylvester-Bradley fixed a compilation issue with MSVC.
Alexander “weej” Jones fixed an example in the README.
Antoine Cœur fixed some typos in the documentation.
jothepro updated links to the Hunter package.
Dave Lee fixed a link in the README.
Joël Lamotte added instruction for using Build2's package manager.
Paul Jurczak fixed an example in the README.
Sonu Lohani fixed a warning.
Carlos Gomes Martinho updated the Conan package source.
Konstantin Podsvirov fixed the MSYS2 package documentation.
Tridacnid improved the CMake tests.
Michael fixed MSVC warnings.
Quentin Barbarat fixed an example in the documentation.
XyFreak fixed a compiler warning.
TotalCaesar659 fixed links in the README.
Tanuj Garg improved the fuzzer coverage for UBSAN input.
AODQ fixed a compiler warning.
jwittbrodt made NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE inline.
pfeatherstone improved the upper bound of arguments of the NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE/NLOHMANN_DEFINE_TYPE_INTRUSIVE macros.
Jan Procházka fixed a bug in the CBOR parser for binary and string values.
T0b1-iOS fixed a bug in the new hash implementation.
Matthew Bauer adjusted the CBOR writer to create tags for binary subtypes.
gatopeich implemented an ordered map container for nlohmann::ordered_json.
Érico Nogueira Rolim added support for pkg-config.
KonanM proposed an implementation for the NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE/NLOHMANN_DEFINE_TYPE_INTRUSIVE macros.
Guillaume Racicot implemented string_view support and allowed C++20 support.
Alex Reinking improved CMake support for FetchContent.
Hannes Domani provided a GDB pretty printer.
Lars Wirzenius reviewed the README file.
Jun Jie fixed a compiler path in the CMake scripts.
Ronak Buch fixed typos in the documentation.
Alexander Karzhenkov fixed a move constructor and the Travis builds.
Leonardo Lima added CPM.Cmake support.
Joseph Blackman fixed a warning.
Yaroslav updated doctest and implemented unit tests.
Martin Stump fixed a bug in the CMake files.
Jaakko Moisio fixed a bug in the input adapters.
bl-ue fixed some Markdown issues in the README file.
William A. Wieselquist fixed an example from the README.
abbaswasim fixed an example from the README.
Remy Jette fixed a warning.
Fraser fixed the documentation.
Ben Beasley updated doctest.
Doron Behar fixed pkg-config.pc.
raduteo fixed a warning.
David Pfahler added the possibility to compile the library without I/O support.
Morten Fyhn Amundsen fixed a typo.
jpl-mac allowed treating the library as a system header in CMake.
Jason Dsouza fixed the indentation of the CMake file.
offa added a link to Conan Center to the documentation.
TotalCaesar659 updated the links in the documentation to use HTTPS.
Rafail Giavrimis fixed the Google Benchmark default branch.
Louis Dionne fixed a conversion operator.
justanotheranonymoususer made the examples in the README more consistent.
Finkman suppressed some -Wfloat-equal warnings.
Ferry Huberts fixed -Wswitch-enum warnings.
Arseniy Terekhin made the GDB pretty-printer robust against unset variable names.
Amir Masoud Abdol updated the Homebrew command as nlohmann/json is now in homebrew-core.
Hallot fixed some -Wextra-semi-stmt warnings.
Giovanni Cerretani fixed -Wunused warnings on JSON_DIAGNOSTICS.
Bogdan Popescu hosts the docset for offline documentation viewers.
Carl Smedstad fixed an assertion error when using JSON_DIAGNOSTICS.
miikka75 provided an important fix to compile C++17 code with Clang 9.
Maarten Becker fixed a warning for shadowed variables.
Cristi Vîjdea fixed typos in the operator[] documentation.
Alex Beregszaszi fixed spelling mistakes in comments.
Dirk Stolle fixed typos in documentation.
Daniel Albuschat corrected the parameter name in the parse documentation.
Prince Mendiratta fixed a link to the FAQ.
Florian Albrechtskirchinger implemented std::string_view support for object keys and made dozens of other improvements.
Qianqian Fang implemented the Binary JData (BJData) format.
pketelsen added macros NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT and NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT.
DarkZeros adjusted to code to not clash with Arduino defines.
flagarde fixed the output of meta() for MSVC.
Giovanni Cerretani fixed a check for std::filesystem.
Dimitris Apostolou fixed a typo.
Ferry Huberts fixed a typo.
Michael Nosthoff fixed a typo.
JungHoon Lee fixed a typo.
Faruk D. fixed the CITATION.CFF file.
Andrea Cocito added a clarification on macro usage to the documentation.
Krzysiek Karbowiak refactored the tests to use CHECK_THROWS_WITH_AS.
Chaoqi Zhang fixed a typo.
ivanovmp fixed a whitespace error.
KsaNL fixed a build error when including <windows.h>.
Andrea Pappacoda moved .pc and .cmake files to share directory.
Wolf Vollprecht added the patch_inplace function.
Jake Zimmerman highlighted common usage patterns in the README file.
NN added the Visual Studio output directory to .gitignore.
Romain Reignier improved the performance of the vector output adapter.
Mike fixed the std::iterator_traits.
Richard Hozák added macro JSON_NO_ENUM to disable default enum conversions.
vakokako fixed tests when compiling with C++20.
Alexander “weej” Jones fixed an example in the README.
Eli Schwartz added more files to the include.zip archive.
Kevin Lu fixed a compilation issue when typedefs with certain names were present.
Trevor Hickey improved the description of an example.
Jef LeCompte updated the year in the README file.
Alexandre Hamez fixed a warning.
Maninderpal Badhan fixed a typo.
kevin-- added a note to an example in the README file.
I fixed a typo.
Gregorio Litenstein fixed the Clang detection.
Andreas Smas added a Doozer badge.
WanCW fixed the string conversion with Clang.
zhaohuaxishi fixed a Doxygen error.
emvivre removed an invalid parameter from CMake.
Tobias Hermann fixed a link in the README file.
Michael fixed a warning.
Ryan Mulder added ensure_ascii to the dump function.
Muri Nicanor fixed the sed discovery in the Makefile.
David Avedissian implemented SFINAE-friendly iterator_traits.
AQNOUCH Mohammed fixed a typo in the README.
Gareth Sylvester-Bradley added operator/= and operator/ to construct JSON pointers.
Michael Macnair added support for afl-fuzz testing.
Berkus Decker fixed a typo in the README.
Illia Polishchuk improved the CMake testing.
Ikko Ashimine fixed a typo.
Raphael Grimm added the possibility to define a custom base class.
tocic fixed typos in the documentation.
Vertexwahn added Bazel build support.
Dirk Stolle fixed typos in the documentation.
DavidKorczynski added a CIFuzz CI GitHub action.
Finkman fixed the debug pretty-printer.
Florian Segginger bumped the years in the README.
haadfida cleaned up the badges of used services.
Arsen Arsenović fixed a build error.
theevilone45 fixed a typo in a CMake file.
Sergei Trofimovich fixed the custom allocator support.
Joyce fixed some security issues in the GitHub workflows.
Nicolas Jakob add vcpkg version badge.
Tomerkm added tests.
No. fixed the use of get<> calls.
taro fixed a typo in the CODEOWNERS file.
Ikko Eltociear Ashimine fixed a typo.
Felix Yan fixed a typo in the README.
HO-COOH fixed a parenthesis in the documentation.
Ivor Wanders fixed the examples to catch exception by const&.
miny1233 fixed a parenthesis in the documentation.
tomalakgeretkal fixed a compilation error.
alferov fixed a compilation error.
Craig Scott fixed a deprecation warning in CMake.
Vyacheslav Zhdanovskiy added macros for serialization-only types.
Mathieu Westphal fixed typos.
scribam fixed the MinGW workflow.
Aleksei Sapitskii added support for Apple's Swift Package Manager.
Benjamin Buch fixed the installation path in CMake.
Colby Haskell clarified the parse error message in case a file cannot be opened.
Juan Carlos Arevalo Baeza fixed the enum conversion.
alferov fixed a version in the documentation.
ss fixed the amalgamation call.
AniketDhemare fixed a version in the documentation.
Philip Müller fixed an example.
Leila Shcheglova fixed a warning in a test.
Alex Prabhat Bara fixed a function name in the documentation.
laterlaugh fixed some typos.
Yuanhao Jia fixed the GDB pretty printer.
Fallen_Breath fixed an example for JSON Pointer.
Nikhil Idiculla fixed some typos.
Griffin Myers updated the Natvis file.
thetimr fixed a typo in the documentation.
Balazs Erseki fixed a URL in the contribution guidelines.
Niccolò Iardella added NLOHMANN_DEFINE_DERIVED_TYPE_* macros.
Borislav Stanimirov allowed overriding the CMake target name.
Captain Crutches made iterator_proxy_value a std::forward_iterator.
Fredrik Sandhei added type conversion support for std::optional.
jh96 added exceptions when nullptr is passed to parse.
Stuart Gorman fixed number parsing when EINTR set in errno.
Dylan Baker generated a pkg-config file that follows the pkg-config conventions.
Tianyi Chen optimized the binary get_number implementation.
peng-wang-cn added type conversion support for multidimensional arrays.
Einars Netlis-Galejs added ONLY_SERIALIZE for NLOHMANN_DEFINE_DERIVED_TYPE_* macros.
Marcel removed alwayslink=True Bazel flag.
Harinath Nampally added diagnostic positions to exceptions.
Nissim Armand Ben Danan fixed NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT with an empty JSON instance.
Michael Valladolid added support for BSON uint64 serialization/deserialization.
Nikhil updated the documentation.
Nebojša Cvetković added support for BJDATA optimized binary array type.
Sushrut Shringarputale added support for diagnostic positions.
kimci86 templated to NLOHMANN_DEFINE_TYPE macros to also support ordered_json.
Richard Topchii added support for VisionOS in the Swift Package Manager.
Robert Chisholm fixed a typo.
zjyhjqs added CPack support.
bitFiedler made GDB pretty printer work with Python 3.8.
Gianfranco Costamagna fixed a compiler warning.
risa2000 made std::filesystem::path conversion to/from UTF-8 encoded string explicit.

Thanks a lot for helping out! Please let me know if I forgot someone.

Used third-party tools

The library itself consists of a single header file licensed under the MIT license. However, it is built, tested, documented, and whatnot using a lot of third-party tools and services. Thanks a lot!

amalgamate.py - Amalgamate C source and header files to create a single header file
American fuzzy lop for fuzz testing
AppVeyor for continuous integration on Windows
Artistic Style for automatic source code indentation
Clang for compilation with code sanitizers
CMake for build automation
Codacy for further code analysis
Coveralls to measure code coverage
Coverity Scan for static analysis
cppcheck for static analysis
doctest for the unit tests
GitHub Changelog Generator to generate the ChangeLog
Google Benchmark to implement the benchmarks
Hedley to avoid re-inventing several compiler-agnostic feature macros
lcov to process coverage information and create an HTML view
libFuzzer to implement fuzz testing for OSS-Fuzz
Material for MkDocs for the style of the documentation site
MkDocs for the documentation site
OSS-Fuzz for continuous fuzz testing of the library (project repository)
Probot for automating maintainer tasks such as closing stale issues, requesting missing information, or detecting toxic comments.
Valgrind to check for correct memory management

Notes

Character encoding

The library supports Unicode input as follows:

Only UTF-8 encoded input is supported, which is the default encoding for JSON according to RFC 8259.
std::u16string and std::u32string can be parsed, assuming UTF-16 and UTF-32 encoding, respectively. These encodings are not supported when reading from files or other input containers.
Other encodings such as Latin-1 or ISO 8859-1 are not supported and will yield parse or serialization errors.
Unicode noncharacters will not be replaced by the library.
Invalid surrogates (e.g., incomplete pairs such as \uDEAD) will yield parse errors.
The strings stored in the library are UTF-8 encoded. When using the default string type (std::string), note that its length/size functions return the number of stored bytes rather than the number of characters or glyphs.
When you store strings with different encodings in the library, calling dump() may throw an exception unless json::error_handler_t::replace or json::error_handler_t::ignore are used as error handlers.
To store wide strings (e.g., std::wstring), you need to convert them to a UTF-8 encoded std::string before, see an example.

Comments in JSON

This library does not support comments by default. It does so for three reasons:

Comments are not part of the JSON specification. You may argue that // or /* */ are allowed in JavaScript, but JSON is not JavaScript.
This was not an oversight: Douglas Crockford wrote on this in May 2012:

I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.

Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
It is dangerous for interoperability if some libraries would add comment support while others don't. Please check The Harmful Consequences of the Robustness Principle on this.

However, you can set set parameter ignore_comments to true in the parse function to ignore // or /* */ comments. Comments will then be treated as whitespace.

Trailing commas

The JSON specification does not allow trailing commas in arrays and objects, and hence this library is treating them as parsing errors by default.

Like comments, you can set parameter ignore_trailing_commas to true in the parse function to ignore trailing commas in arrays and objects. Note that a single comma as the only content of the array or object ([,] or {,}) is not allowed, and multiple trailing commas ([1,,]) are not allowed either.

This library does not add trailing commas when serializing JSON data.

For more information, see JSON With Commas and Comments (JWCC).

Order of object keys

By default, the library does not preserve the insertion order of object elements. This is standards-compliant, as the JSON standard defines objects as "an unordered collection of zero or more name/value pairs".

If you do want to preserve the insertion order, you can try the type nlohmann::ordered_json. Alternatively, you can use a more sophisticated ordered map like tsl::ordered_map (integration) or nlohmann::fifo_map (integration).

See the documentation on object order for more information.

Memory Release

We checked with Valgrind and the Address Sanitizer (ASAN) that there are no memory leaks.

If you find that a parsing program with this library does not release memory, please consider the following case, and it may be unrelated to this library.

Your program is compiled with glibc. There is a tunable threshold that glibc uses to decide whether to actually return memory to the system or whether to cache it for later reuse. If in your program you make lots of small allocations and those small allocations are not a contiguous block and are presumably below the threshold, then they will not get returned to the OS. Here is a related issue #1924.

Further notes

The code contains numerous debug assertions which can be switched off by defining the preprocessor macro NDEBUG, see the documentation of assert. In particular, note operator[] implements unchecked access for const objects: If the given key is not present, the behavior is undefined (think of a dereferenced null pointer) and yields an assertion failure if assertions are switched on. If you are not sure whether an element in an object exists, use checked access with the at() function. Furthermore, you can define JSON_ASSERT(x) to replace calls to assert(x). See the documentation on runtime assertions for more information.
As the exact number type is not defined in the JSON specification, this library tries to choose the best fitting C++ number type automatically. As a result, the type double may be used to store numbers which may yield floating-point exceptions in certain rare situations if floating-point exceptions have been unmasked in the calling code. These exceptions are not caused by the library and need to be fixed in the calling code, such as by re-masking the exceptions prior to calling library functions.
The code can be compiled without C++ runtime type identification features; that is, you can use the -fno-rtti compiler flag.
Exceptions are used widely within the library. They can, however, be switched off with either using the compiler flag -fno-exceptions or by defining the symbol JSON_NOEXCEPTION. In this case, exceptions are replaced by abort() calls. You can further control this behavior by defining JSON_THROW_USER (overriding throw), JSON_TRY_USER (overriding try), and JSON_CATCH_USER (overriding catch). Note that JSON_THROW_USER should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior. Note the explanatory what() string of exceptions is not available for MSVC if exceptions are disabled, see #2824. See the documentation of exceptions for more information.

Execute unit tests

To compile and run the tests, you need to execute

mkdir build
cd build
cmake .. -DJSON_BuildTests=On
cmake --build .
ctest --output-on-failure

Note that during the ctest stage, several JSON test files are downloaded from an external repository. If policies forbid downloading artifacts during testing, you can download the files yourself and pass the directory with the test files via -DJSON_TestDataDirectory=path to CMake. Then, no Internet connectivity is required. See issue #2189 for more information.

If the testdata is not found, several test suites will fail like this:

===============================================================================
json/tests/src/make_test_data_available.hpp:21:
TEST CASE:  check test suite is downloaded

json/tests/src/make_test_data_available.hpp:23: FATAL ERROR: REQUIRE( utils::check_testsuite_downloaded() ) is NOT correct!
  values: REQUIRE( false )
  logged: Test data not found in 'json/cmake-build-debug/json_test_data'.
          Please execute target 'download_test_data' before running this test suite.
          See <https://github.com/nlohmann/json#execute-unit-tests> for more information.

===============================================================================

In case you have downloaded the library rather than checked out the code via Git, test cmake_fetch_content_configure will fail. Please execute ctest -LE git_required to skip these tests. See issue #2189 for more information.

Some tests are requiring network to be properly execute. They are labeled as git_required. Please execute ctest -LE git_required to skip these tests. See issue #4851 for more information.

Some tests change the installed files and hence make the whole process not reproducible. Please execute ctest -LE not_reproducible to skip these tests. See issue #2324 for more information. Furthermore, assertions must be switched off to ensure reproducible builds (see discussion 4494).

Note you need to call cmake -LE "not_reproducible|git_required" to exclude both labels. See issue #2596 for more information.

As Intel compilers use unsafe floating point optimization by default, the unit tests may fail. Use flag /fp:precise then.

organicmaps/organicmaps

🍃 Organic Maps is a free Android & iOS offline maps app for more than 6M travelers, tourists, hikers, and cyclists. It uses crowd-sourced OpenStreetMap data and is developed with love by the community. No ads, no tracking, no data collection, no crapware. Please donate to support the development!

Organic Maps

Organic Maps is a privacy-first offline maps & GPS app for hiking, cycling, biking, and driving. Absolutely free. No ads. No tracking. Created and maintained by MapsWithMe (MAPS.ME) founders, developed with love by the open-source community. Powered by OpenStreetMap data. Installed by over 6 million users worldwide.

Features

Organic Maps is the ultimate companion app for travellers, tourists, hikers, and cyclists:

Detailed offline maps with places that don't exist on other maps, thanks to OpenStreetMap
Cycling routes, hiking trails, and walking paths
Contour lines, elevation profiles, peaks, and slopes
Turn-by-turn walking, cycling, and car navigation with voice guidance
Subway maps and public transport routes
Fast offline search on the map
Bookmarks and tracks import and export in KML, KMZ, GPX, GeoJSON formats
Dark Mode to protect your eyes
Countries and regions don't take a lot of space
Wikipedia articles for places of interest
Free and open-source

Why Organic?

Organic Maps is pure and organic, made with love:

Respects your privacy
Saves your battery
No unexpected mobile data charges
Offline and fast
Open-source alternative to Google Maps, Apple Maps, and MAPS.ME

Organic Maps is free from trackers and other bad stuff:

No ads
No tracking
No data collection
No phoning home
No annoying registration
No mandatory tutorials
No noisy email spam
No push notifications
No crapware
~~No pesticides~~ Purely organic!

The Android application is verified by the Exodus Privacy Project:

The iOS application is verified by TrackerControl for iOS:

Organic Maps doesn't request excessive permissions to spy on you:

At Organic Maps, we believe that privacy is a fundamental human right:

Organic Maps is an indie community-driven open-source project
We protect your privacy from Big Tech's prying eyes
Stay safe no matter where you are

Reject surveillance - embrace your freedom.

Give Organic Maps a try!

Who is paying for the development?

The app is free for everyone, so we rely on your donations. Please donate at organicmaps.app/donate to support the project!

Beloved institutional sponsors below have provided targeted grants to cover some infrastructure costs and fund development of new selected features:

	The Search & Fonts improvement project has been funded through NGI0 Entrust Fund. NGI0 Entrust Fund is established by the NLnet Foundation with financial support from the European Commission's Next Generation Internet programme, under the aegis of DG Communications Networks, Content and Technology under grant agreement No 101069594.
	Google backed 5 student's projects in the Google Summer of Code program during 2022 and 2023 programs. Noteworthy projects included Android Auto and Wikipedia Dump Extractor.
	Mythic Beasts ISP provides us two virtual servers with 400 TB/month of free bandwidth to host and serve maps downloads and updates.
	44+ Technologies is providing us with a free dedicated server worth around $12,000/year to serve maps across Vietnam & Southeast Asia.
	FUTO has awarded $1000 micro-grant to Organic Maps in February 2023.

The majority of all expenses have been funded by founders of the project since its inception. The project is far from achieving any sort of financial sustainability. The current level of voluntary donations falls significantly short of covering efforts needed to sustain the app. Any new developments of features are beyond the scope of possibility due to the absence of the necessary financial resources.

Please consider donating if you want to see this open-source project thriving, not dying. There are other ways how to support the project. No coding skills required.

Governance

See docs/GOVERNANCE.md.

Contributing

If you want to build the project, check docs/INSTALL.md. If you want to help the project, see docs/CONTRIBUTING.md. You can help in many ways, the ability to code is not necessary.

Beta

Please join our beta program, suggest your features, and report bugs:

Feedback

Rate us on the App Store and Google Play.
Star us on Github.
Report bugs or issues to the issue tracker.
Subscribe to our Telegram Channel or to the [matrix] space for updates.
Join our Telegram Group to discuss with other users.
- Присоединяйтесь к нашей русскоязычной группе в Telegram для обратной связи и помощи.
- Diğer kullanıcılarla tartışmak için Telegram Grubumuza katılın.
- Rejoignez notre groupe Telegram pour obtenir de l'aide.
Contact us by email.
Follow our updates in social media:
- Mastodon
- Facebook
- X (Twitter)
- Instagram
- Bluesky
- Threads
- Reddit
- LinkedIn
- TikTok

The Organic Maps community abides by the CNCF code of conduct.

License and Copyrights

The code is Licensed under the Apache License, Version 2.0. See LICENSE, NOTICE, data/copyright.html and .reuse/dep5 for more information.

Binary data files (including, but not limited to .mwm map files) are provided under a separate license. See DATA_LICENSE.txt for details.

Attribution for forks and derivative apps based on Organic Maps

If you use Organic Maps binary data (e.g. maps), source code, or its user interface in your project, include a visible, human-readable mention of the “Organic Maps Project” and a clickable link to https://organicmaps.app. To respect the work of all project contributors and to comply with license attribution terms, this notice should appear in user-visible locations, such as the product’s “About” and “Main Menu” screens.

🤝 White-label

For inquiries about white-labeling or using our servers for your products, please contact us in advance at:

legal@organicmaps.app

Thank you!

deepseek-ai/FlashMLA

FlashMLA: Efficient Multi-head Latent Attention Kernels

FlashMLA

Introduction

FlashMLA is DeepSeek's library of optimized attention kernels, powering the DeepSeek-V3 and DeepSeek-V3.2-Exp models. This repository contains the following implementations:

Sparse Attention Kernels

These kernels power DeepSeek Sparse Attention (DSA), as introduced in this paper.

Token-level sparse attention for the prefill stage
Token-level sparse attention for the decoding stage, with FP8 KV cache

Dense Attention Kernels

Dense attention for the prefill stage
Dense attention for the decoding stage

News

2025.09.29 Release of Sparse Attention Kernels: With the launch of DeepSeek-V3.2, we are releasing the corresponding token-level sparse attention kernels. These kernels power the model's DeepSeek Sparse Attention (DSA) and achieve up to 640 TFlops during prefilling and 410 TFlops during decoding. We also release a deep-dive blog for our new FP8 sparse decoding kernel. Check it out here.
2025.08.01 Kernels for MHA on SM100: Thanks to NVIDIA's PR for MHA forward / backward kernels on SM100!
2025.04.22 Deep-Dive Blog: We'd love to share the technical details behind the new FlashMLA kernel! Check out our deep-dive write-up here.
2025.04.22 Performance Update: We're excited to announce the new release of Flash MLA, which delivers 5% ~ 15% performance improvement for compute-bound workloads, achieving up to 660 TFlops on NVIDIA H800 SXM5 GPUs. The interface of the new version is fully compatible with the old one. Simply upgrade to the new version for an immediate performance boost! 🚀🚀🚀

Performance

Test & benchmark MLA decoding (Sparse & Dense):

python tests/test_flash_mla_dense_decoding.py
python tests/test_flash_mla_sparse_decoding.py

The dense MLA decoding kernel achieves up to 3000 GB/s in memory-bound configuration and 660 TFLOPS in computation-bound configuration on H800 SXM5 with CUDA 12.8. The token-level sparse MLA decoding kernel (which uses an FP8 KV cache while performing the matrix multiplication in bfloat16) achieves 410 TFLOPS in compute-bound configuration on H800 SXM5 with CUDA 12.8, and achieves up to 350 TFlops on B200 (which is not really optimized yet).

Test & benchmark MHA prefill (Dense):

python tests/test_fmha_sm100.py

It achieves up to 1460 TFlops in forward and 1000 TFlops in backward computation on B200, as reported by NVIDIA.

Test & benchmark MLA prefill (Sparse):

python tests/test_flash_mla_sparse_prefill.py

It achieves up to 640 TFlops in forward computation on H800 SXM5 with CUDA 12.8, and achieves up to 1450 TFlops on B200, CUDA 12.9.

Requirements

SM90 / SM100 (See the support matrix below)
CUDA 12.8 and above (CUDA 12.9+ is required for SM100 kernels)
PyTorch 2.0 and above

Support matrix:

Kernel	GPU Architecture	MLA Mode [2]	KVCache Format
Dense Decoding	SM90	MQA	BF16
Sparse Decoding	SM90 & SM100	MQA	FP8 [1]
Dense Prefill	SM100	MHA
Sparse Prefill	SM90 & SM100	MQA

[1]: For more details on using FP8 KV cache, see documents below.

[2]: Here "MLA Mode" refers to the mode used for MLA calculation. MQA stands for Multi-Query Attention mode (i.e. head_dim_k = 576 with head_dim_v = 512), while MHA stands for Multi-Head Attention mode (i.e. head_dim_k = 192 / 128 with head_dim_v = 128). For a detailed explanation of these modes, please refer to the appendix of DeepSeek V3.2's Paper.

Installation

git clone https://github.com/deepseek-ai/FlashMLA.git flash-mla
cd flash-mla
git submodule update --init --recursive
pip install -v .

Usage

MLA Decoding

To use the MLA decoding kernels, call get_mla_metadata once before the decoding loop to get the tile scheduler metadata. Then, call flash_mla_with_kvcache in each decoding step. For example:

from flash_mla import get_mla_metadata, flash_mla_with_kvcache

tile_scheduler_metadata, num_splits = get_mla_metadata(
    cache_seqlens,
    s_q * h_q // h_kv,
    h_kv,
    h_q,
    is_fp8,
    topk,
)

for i in range(num_layers):
    ...
    o_i, lse_i = flash_mla_with_kvcache(
        q_i, kvcache_i, block_table, cache_seqlens, dv,
        tile_scheduler_metadata, num_splits,
        is_causal, is_fp8_kvcache, indices,
    )
    ...

Where

s_q is the number of q tokens per q sequence. If MTP (speculative decoding) is disabled, it should be 1.
h_kv is the number of key-value heads.
h_q is the number of query heads.

FP8 KV Cache: If is_fp8_kvcache is set to True, the kernel reads the KV cache in the "FP8 with scale" format (described below). It dequantizes the cache to bfloat16 and performs attention computation in bfloat16. The output is also in bfloat16.

In the "FP8 with scale" format, each token's KV cache is 656 Bytes, structured as:

First 512 bytes: The "quantized NoPE" part, containing 512 float8_e4m3 values.
Next 16 bytes: Scale factors, containing 4 float32 values. The first float32 is the scale for the first 128 float8_e4m3 values, the second for the next 128, and so on.
Last 128 bytes: The "RoPE" part, containing 64 bfloat16 values. This part is not quantized for accuracy.

See tests/quant.py for quantization and dequantization details.

Sparse Attention (indices tensor): The indices tensor (if provided) enables token-level sparse attention by instructing the kernel to compute attention only for specified tokens.

Shape: indices should be a 3D tensor of shape (batch_size, seq_len_q, topk).
Format: indices_in_kvcache[i][j][k] = (the index of the page block where token t resides) * page_block_size + (the offset of token t within the page block), where t is the k-th token for the j-th query sequence in the i-th batch. Since the index of the page block has already been encoded into indices_in_kvcache, the kernel does not require the block_table parameter.
Invalid entries: Set invalid indices to -1.

Return Values: The kernel returns (out, lse), where:

out is the attention result.
lse is the log-sum-exp value of the attention scores for each query head.

See tests/test_flash_mla_decoding.py for a complete example.

Sparse MLA Prefill

For the sparse MLA prefill kernel, call flash_mla_sparse_fwd directly with the following parameters:

q: Query tensor of shape [s_q, h_q, d_qk]
kv: Key-Value tensor of shape [s_kv, h_kv, d_qk]
indices: Indices tensor of shape [s_q, h_kv, topk]
sm_scale: A scalar value

Note on batching: This kernel does not support a batch dimension. For multi-batch inference, reshape the input tensors and adjust the indices parameter to simulate batch processing.

Invalid indices: Set invalid entries in indices to -1 or any number >= s_kv.

Return Values and Equivalent PyTorch Code: The kernel returns (out, max_logits, lse). This is equivalent to the following PyTorch operations:

Q: [s_q, h_q, d_qk], bfloat16
kv: [s_kv, h_kv, d_qk], bfloat16
indices: [s_q, h_kv, topk], int32

kv = kv.squeeze(1)  # [s_kv, d_qk], h_kv must be 1
indices = indices.squeeze(1)    # [s_q, topk]
focused_kv = kv[indices]    # For the i-th sequence (s_q), the corresponding KV tokens are selected from the KV cache based on indices[i, :]. This operation results in a tensor of shape [s_q, topk, d_qk].

P = (Q @ focused_kv.transpose(-1, -2)) * sm_scale * math.log2(math.e)    # [s_q, h_q, topk]
max_logits = P.max(dim=-1) # [s_q, h_q]
lse = log2sumexp2(P, dim=-1, base=2)   # [s_q, h_q]，"log2sumexp2" means that the exponentiation and logarithm are base-2
S = exp2(P - lse)      # [s_q, h_q, topk]
out = S @ focused_kv  # [s_q, h_q, d_qk]

return (out, max_logits, lse)

See tests/test_flash_mla_prefill.py for a complete example.

Dense MHA Prefill

This kernel implements the standard dense Multi-Head Attention (MHA) forward and backward operations. It can be called using:

flash_attn_varlen_func
flash_attn_varlen_qkvpacked_func
flash_attn_varlen_kvpacked_func

The usage is similar to the flash_attn package. See tests/test_fmha_sm100.py for a complete example.

Acknowledgement

FlashMLA is inspired by FlashAttention 2&3 and cutlass projects.

Community Support

MetaX

For MetaX GPUs, visit the official website: MetaX.

The corresponding FlashMLA version can be found at: MetaX-MACA/FlashMLA

Moore Threads

For the Moore Threads GPU, visit the official website: Moore Threads.

The corresponding FlashMLA version is available on GitHub: MooreThreads/MT-flashMLA.

Hygon DCU

For the Hygon DCU, visit the official website: Hygon Developer.

The corresponding FlashMLA version is available here: OpenDAS/MLAttention.

Intellifusion

For the Intellifusion NNP, visit the official website: Intellifusion.

The corresponding FlashMLA version is available on Gitee: Intellifusion/tyllm.

Iluvatar Corex

For Iluvatar Corex GPUs, visit the official website: Iluvatar Corex.

The corresponding FlashMLA version is available on GitHub: Deep-Spark/FlashMLA

AMD Instinct

For AMD Instinct GPUs, visit the official website: AMD Instinct.

The corresponding FlashMLA version can be found at: AITER/MLA

Citation

@misc{flashmla2025,
      title={FlashMLA: Efficient Multi-head Latent Attention Kernels},
      author={Jiashi Li, Shengyu Liu},
      year={2025},
      publisher = {GitHub},
      howpublished = {\url{https://github.com/deepseek-ai/FlashMLA}},
}

microsoft/onnxruntime

ONNX Runtime: cross-platform, high performance ML inferencing and training accelerator

ONNX Runtime is a cross-platform inference and training machine-learning accelerator.

ONNX Runtime inference can enable faster customer experiences and lower costs, supporting models from deep learning frameworks such as PyTorch and TensorFlow/Keras as well as classical machine learning libraries such as scikit-learn, LightGBM, XGBoost, etc. ONNX Runtime is compatible with different hardware, drivers, and operating systems, and provides optimal performance by leveraging hardware accelerators where applicable alongside graph optimizations and transforms. Learn more →

ONNX Runtime training can accelerate the model training time on multi-node NVIDIA GPUs for transformer models with a one-line addition for existing PyTorch training scripts. Learn more →

Get Started & Resources

General Information: onnxruntime.ai
Usage documentation and tutorials: onnxruntime.ai/docs
YouTube video tutorials: youtube.com/@ONNXRuntime
Upcoming Release Roadmap
Companion sample repositories:
- ONNX Runtime Inferencing: microsoft/onnxruntime-inference-examples
- ONNX Runtime Training: microsoft/onnxruntime-training-examples
Plugin EP repositories:
- ONNX Runtime QNN Plugin EP: onnxruntime/onnxruntime-qnn

Releases

The current release and past releases can be found here: https://github.com/microsoft/onnxruntime/releases.

For details on the upcoming release, including release dates, announcements, features, and guidance on submitting feature requests, please visit the release roadmap: https://onnxruntime.ai/roadmap.

Data/Telemetry

Windows distributions of this project may collect usage data and send it to Microsoft to help improve our products and services. See the privacy statement for more details.

Contributions and Feedback

We welcome contributions! Please see the contribution guidelines.

For feature requests or bug reports, please file a GitHub Issue.

For general discussion or questions, please use GitHub Discussions.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

License

This project is licensed under the MIT License.

azerothcore/azerothcore-wotlk

Complete Open Source and Modular solution for MMO

AzerothCore

Build Status

Introduction

AzerothCore is an open-source game server application and framework designed for hosting massively multiplayer online role-playing games (MMORPGs). It is based on the popular MMORPG World of Warcraft (WoW) and seeks to recreate the gameplay experience of the original game from patch 3.3.5a.

The original code is based on MaNGOS, TrinityCore, and SunwellCore and has since then had extensive development to improve stability, in-game mechanics, and modularity to the game. AC has also grown into a community-driven project with a significant number of contributors and developers. It is written in C++ and provides a solid foundation for creating private servers that mimic the mechanics and behavior of the official WoW servers.

Philosophy

Our main goal is to create a playable game server, offering a fully working in-game experience.

Here are the main points we focus on:

Stability
- We make sure all changes pass the CIs before being merged into the master branch.
Blizzlike content
- We strive to make all in-game content to be blizzlike. Therefore we have a high standard for fixes being made.
Customization
- It is easy to customize your experience using modules.
Community driven
- AzerothCore has an active community of developers, contributors, and users who collaborate, share knowledge, and provide support through forums, Discord channels, and other communication platforms.

Modules

AzerothCore is designed to be highly modular, allowing developers to extend and customize the game to suit their preferences or create unique gameplay experiences. This flexibility enables the addition of custom features, content, and modifications.

We have a lot of modules already made by the community, many of which can be found in the Module Catalogue.

Installation

Detailed installation instructions are available here.

Contributing

AzerothCore can also serve as a learning resource for aspiring developers who want to understand how WoW servers work, how MMORPGs are structured, how game server emulators are created, or to improve their C++ and SQL knowledge.

If you want to contribute to the project, you will find a lot of resources that will guide you in our wiki.

We also recommend you read our Contributor Covenant Code of Conduct.

Feel free to join our Discord server.

Click on the "⭐ Star" button to help us gain more visibility on Github!

Authors & Contributors

The project was born in 2016 based on SunwellCore. Unfortunately, SunwellCore was published without any git history, so on git there are no credits for all the contributors before 2016.

You can check the authors file for more details.

License

The AzerothCore source code is released under the GNU GPL v2

It's important to note that AzerothCore is not an official Blizzard Entertainment product, and it is not affiliated with or endorsed by World of Warcraft or Blizzard Entertainment. AzerothCore does not in any case sponsor nor support illegal public servers. If you use this project to run an illegal public server and not for testing and learning it is your own personal choice.

Special thanks

JetBrains is providing free open-source licenses to the AzerothCore developers.

google-deepmind/mujoco

Multi-Joint dynamics with Contact. A general purpose physics simulator.

MuJoCo stands for Multi-Joint dynamics with Contact. It is a general purpose physics engine that aims to facilitate research and development in robotics, biomechanics, graphics and animation, machine learning, and other areas which demand fast and accurate simulation of articulated structures interacting with their environment.

This repository is maintained by Google DeepMind.

MuJoCo has a C API and is intended for researchers and developers. The runtime simulation module is tuned to maximize performance and operates on low-level data structures that are preallocated by the built-in XML compiler. The library includes interactive visualization with a native GUI, rendered in OpenGL. MuJoCo further exposes a large number of utility functions for computing physics-related quantities.

We also provide Python bindings and a plug-in for the Unity game engine.

Documentation

MuJoCo's documentation can be found at mujoco.readthedocs.io. Upcoming features due for the next release can be found in the changelog in the "latest" branch.

Getting Started

There are two easy ways to get started with MuJoCo:

Run simulate on your machine. This video shows a screen capture of simulate, MuJoCo's native interactive viewer. Follow the steps described in the Getting Started section of the documentation to get simulate running on your machine.
Explore our online IPython notebooks. If you are a Python user, you might want to start with our tutorial notebooks running on Google Colab:

The introductory tutorial teaches MuJoCo basics:
The Model Editing tutorial shows how to create and edit models procedurally:
The rollout tutorial shows how to use the multithreaded rollout module:
The LQR tutorial synthesizes a linear-quadratic controller, balancing a humanoid on one leg:
The least-squares tutorial explains how to use the Python-based nonlinear least-squares solver:
The MJX tutorial provides usage examples of MuJoCo XLA, a branch of MuJoCo written in JAX:
The differentiable physics tutorial trains locomotion policies with analytical gradients automatically derived from MuJoCo's physics step:

Installation

Prebuilt binaries

Versioned releases are available as precompiled binaries from the GitHub releases page, built for Linux (x86-64 and AArch64), Windows (x86-64 only), and macOS (universal). This is the recommended way to use the software.

Building from source

Users who wish to build MuJoCo from source should consult the build from source section of the documentation. However, note that the commit at the tip of the main branch may be unstable.

Python (>= 3.10)

The native Python bindings, which come pre-packaged with a copy of MuJoCo, can be installed from PyPI via:

pip install mujoco

Note that Pre-built Linux wheels target manylinux2014, see here for compatible distributions. For more information such as building the bindings from source, see the Python bindings section of the documentation.

Versioning

We aim to release MuJoCo in the first week of each month. Our versioning standards changed to modified Semantic Versioning in 3.5.0, see versioning for details.

Contributing

We welcome community engagement: questions, requests for help, bug reports and feature requests. To read more about bug reports, feature requests and more ambitious contributions, please see our contributors guide and style guide.

Asking Questions

Questions and requests for help are welcome as a GitHub "Asking for Help" Discussion and should focus on a specific problem or question.

Bug reports and feature requests

GitHub Issues are reserved for bug reports, feature requests and other development-related subjects.

Related software

MuJoCo is the backbone for numerous environment packages. Below we list several bindings and converters.

Bindings

These packages give users of various languages access to MuJoCo functionality:

First-party bindings:

Python bindings
- dm_control, Google DeepMind's related environment stack, includes PyMJCF, a module for procedural manipulation of MuJoCo models.
JavaScript bindings and WebAssembly support (inspired stillonearth and zalo's community projects; mjswan extends these with real-time policy control, interactive force application, and more).
C# bindings and Unity plug-in

Third-party bindings:

MATLAB Simulink: Simulink Blockset for MuJoCo Simulator by Manoj Velmurugan.
Swift: swift-mujoco
Java: mujoco-java
Julia: MuJoCo.jl
Rust: MuJoCo-rs

Converters

OpenSim: MyoConverter converts OpenSim models to MJCF.
SDFormat: gz-mujoco is a two-way SDFormat <-> MJCF conversion tool.
OBJ: obj2mjcf a script for converting composite OBJ files into a loadable MJCF model.
onshape: Onshape to Robot Converts onshape CAD assemblies to MJCF.

Citation

If you use MuJoCo for published research, please cite:

@inproceedings{todorov2012mujoco,
  title={MuJoCo: A physics engine for model-based control},
  author={Todorov, Emanuel and Erez, Tom and Tassa, Yuval},
  booktitle={2012 IEEE/RSJ International Conference on Intelligent Robots and Systems},
  pages={5026--5033},
  year={2012},
  organization={IEEE},
  doi={10.1109/IROS.2012.6386109}
}

License and Disclaimer

ReStructuredText documents, images, and videos in the doc directory are made available under the terms of the Creative Commons Attribution 4.0 (CC BY 4.0) license. You may obtain a copy of the License at https://creativecommons.org/licenses/by/4.0/legalcode.

Source code is licensed under the Apache License, Version 2.0. You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0.

This is not an officially supported Google product.

GitHub C++ Monthly Trending

ggml-org/llama.cpp

llama.cpp

Recent API changes

Hot topics

Quick start

Description

Text-only

Multimodal

Supported backends

Obtaining and quantizing models

llama-cli

A CLI tool for accessing and experimenting with most of llama.cpp's functionality.

llama-server

A lightweight, OpenAI API compatible, HTTP server for serving LLMs.

llama-perplexity

A tool for measuring the perplexity [1] (and other quality metrics) of a model over a given text.

llama-bench

Benchmark the performance of the inference for various parameters.

llama-simple

A minimal example for implementing apps with llama.cpp. Useful for developers.

Contributing

Other documentation

Development documentation

Seminal papers and background on the models

XCFramework

Completions

Bash Completion

Dependencies

imputnet/helium

Helium

Downloads

Helium repos

Platform packaging and tooling

Web services and Helium components

Development

Contributing

Credits

The Chromium project

ungoogled-chromium

Other Chromium browsers

License

ikawrakow/ik_llama.cpp

ik_llama.cpp: llama.cpp fork with better CPU performance

TL;DR

Quickstart

Prerequisites

Build for CPU

Build for GPU

Step-by-step instructions for a case of a successful Windows build

Run

Step by step guide for ik_llama.cpp in podman/docker container including llama-swap

Common parameters and options

Latest News

Model Support

Quantization

Quantization additions

Trellis quants (IQ1_KT, IQ2_KT, IQ3_KT, IQ4_KT)

IQK quants

Hadamard transforms for K-cache

Hadamard transforms for V-cache

MXFP4 as used in gpt-oss models

Quantization improvements

Quantization performance improvements

Features

Performance improvements

Flash-MLA

Fixes

Resources

Testing

Function Calls Tests

Contributing

License

Development documentation

Seminal papers and background on the models

Completions

Bash Completion

Dependencies

ValveSoftware/Proton

Introduction

`llama-cli`

A CLI tool for accessing and experimenting with most of `llama.cpp`'s functionality.

`llama-server`

`llama-perplexity`

A tool for measuring the perplexity ^[1] (and other quality metrics) of a model over a given text.

`llama-bench`

`llama-simple`

A minimal example for implementing apps with `llama.cpp`. Useful for developers.

Trellis quants (`IQ1_KT`, `IQ2_KT`, `IQ3_KT`, `IQ4_KT`)

`compile_commands.json`