fory

**Apache Fory™** is a blazingly fast multi-language serialization framework for idiomatic domain objects, schema IDL, and cross-language data exchange. ## Why Fory Fory is built for fast, compact serialization across languages and implementations. It works with idiomatic objects in each language, supports shared schemas when you need a contract, and preserves object features such as shared and circular references. - **Efficient Cross-Language Encoding**: Exchange payloads across supported languages with compact binary encoding, metadata packing, schema evolution, shared/circular references, and polymorphic runtime types. - **Domain Objects First**: Serialize Java classes, Python dataclasses, Go structs, Rust/C++ structs, and generated or annotated model types directly. Preserve shared and circular references when object identity matters. - **Reference-Aware Schema IDL**: Support shared and circular references directly in the schema, alongside numbers, strings, lists, maps, arrays, enums, structs, and unions. Define schemas once, then generate native domain objects for each language without forcing wrapper types into user code. - **Optimized Implementations**: Java JIT serializers and generated/static serializers in other language implementations keep hot paths fast and payloads compact. - **Language And Platform Support**: Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, and Kotlin, including GraalVM native image, Android, Dart VM/Flutter/web, and Node.js/browser JavaScript. For same-language workloads, Fory provides native serialization modes that support broader language-specific object models: - **Java Native Serialization**: A high-performance replacement for JDK serialization, Hessian, Kryo, and FST in Java-only systems. It supports JDK custom serialization semantics. - **Python Native Serialization**: A faster and more compact replacement for `pickle` and `cloudpickle` in Python-only systems. It supports classes, modules, functions, and custom object state, with fine-grained deserialization controls through `DeserializationPolicy`. Fory also provides specialized formats for other data-processing requirements: - **Row Format**: Read fields, arrays, and nested values without rebuilding complete objects, with zero-copy access and partial reads. - **[Fory JSON](java/fory-json/README.md)**: A Java JSON serialization framework built for maximum throughput through runtime-generated codecs and optimized readers and writers. Supports Java 8 and later on standard JDKs, GraalVM native images, and Android, including Java 17 records. ## Performance Benchmarks show Fory delivering higher throughput and smaller serialized payloads than common serialization frameworks on representative workloads. Java has the broadest comparison set; the other charts show language-specific results across supported languages. **Java** [Benchmarks](docs/benchmarks/index.md) In Java serialization benchmarks, Fory reaches up to **170x** the throughput of JDK serialization on selected workloads.

**Python** [Benchmarks](benchmarks/python)

**Rust** [Benchmarks](benchmarks/rust)

Benchmarks for C++, Go, JavaScript/TypeScript, C#, Swift, and Dart **C++** [Benchmarks](benchmarks/cpp)

**Go** [Benchmarks](benchmarks/go)

**JavaScript/TypeScript** [Benchmarks](docs/benchmarks/object-serialization/xlang/javascript)

**C#** [Benchmarks](docs/benchmarks/object-serialization/xlang/csharp)

**Swift** [Benchmarks](docs/benchmarks/object-serialization/xlang/swift)

**Dart** [Benchmarks](docs/benchmarks/object-serialization/xlang/dart)

## Installation Pick your language and run the package-manager command, or paste the dependency block into your build file. **Java** Maven: ```xml org.apache.fory fory-core 1.7.3 ``` Gradle: ```gradle implementation "org.apache.fory:fory-core:1.7.3" ``` On JDK25+, opening `java.lang.invoke` to Fory core is also recommended. It avoids the current-JDK Unsafe fallback and is required when Unsafe access is disabled or unavailable, including with `--sun-misc-unsafe-memory-access=deny`. Use `ALL-UNNAMED` when Fory is on the classpath: ```bash --add-opens=java.base/java.lang.invoke=ALL-UNNAMED ``` Use the Fory core module name when Fory is on the module path: ```bash --add-opens=java.base/java.lang.invoke=org.apache.fory.core ``` **Scala** sbt: ```scala libraryDependencies += "org.apache.fory" %% "fory-scala" % "1.7.3" ``` **Kotlin** Gradle: ```kotlin implementation("org.apache.fory:fory-kotlin:1.7.3") ``` Maven: ```xml org.apache.fory fory-kotlin 1.7.3 ``` **Python** ```bash pip install pyfory ``` For row-format support: ```bash pip install "pyfory[format]" ``` **Rust** `Cargo.toml`: ```toml [dependencies] fory = "1.7.3" ``` **C++** CMake: ```cmake include(FetchContent) FetchContent_Declare( fory GIT_REPOSITORY https://github.com/apache/fory.git GIT_TAG v1.7.3 SOURCE_SUBDIR cpp ) FetchContent_MakeAvailable(fory) target_link_libraries(my_app PRIVATE fory::serialization) ``` Bazel: ```bazel # MODULE.bazel bazel_dep(name = "fory", version = "1.7.3") git_override(module_name = "fory", remote = "https://github.com/apache/fory.git", commit = "v1.7.3") # BUILD deps = ["@fory//cpp/fory/serialization:fory_serialization"] ``` When building C++ with MSVC, enable the conforming preprocessor option `/Zc:preprocessor`; see the C++ installation guide for setup details. See the [C++ installation guide](https://fory.apache.org/docs/object-serialization/cpp/#installation) for complete CMake, Bazel, and source-build details. **Go** ```bash go get github.com/apache/fory/go/fory ``` **JavaScript/TypeScript** ```bash npm install @apache-fory/core ``` For the Node.js string fast path: ```bash npm install @apache-fory/core @apache-fory/hps ``` **C#** ```bash dotnet add package Apache.Fory --version 1.7.3 ``` **Dart** ```bash dart pub add fory:^1.7.3 dart pub add dev:build_runner ``` **Swift** Add Fory to `Package.swift`: ```swift dependencies: [ .package(url: "https://github.com/apache/fory.git", exact: "1.7.3") ], targets: [ .target( name: "YourTarget", dependencies: [.product(name: "Fory", package: "fory")] ) ] ``` See the [Swift guide](https://fory.apache.org/docs/object-serialization/swift/) for generated serializer setup. **Development From Source** See [docs/development/index.md](docs/development/index.md). Snapshots for Java, Scala, and Kotlin are available from `https://repository.apache.org/snapshots/` with the matching `-SNAPSHOT` version. ## Choose a Serialization Format | Format | Use it when | Start here | | ---------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------- | | Xlang binary (default) | Data crosses language boundaries | [Cross-language interoperability](docs/object-serialization/xlang.md) | | Native binary | Producer and consumer are in the same runtime family | [Native guide](docs/object-serialization/native.md) | | Row format | You need random field access or analytics-style partial reads | [Row Format](docs/row-format/index.md) | | Fory JSON | Java applications need high-performance standard JSON | [Fory JSON](java/fory-json/README.md) | For Java, Scala, Kotlin, Python, C++, Go, and Rust, use native mode for same-language traffic. It avoids xlang's cross-language type mapping and metadata constraints, stays closer to each language's native type system, and supports broader language-specific object graphs. Use it when both producer and consumer are in the same language family and you want the native object model rather than a portable cross-language schema. For Java/JVM-only systems, native mode is the replacement path for JDK serialization, Kryo, FST, Hessian, and Java-only Protocol Buffers payloads. For Python-only systems, native mode is the replacement path for pickle and cloudpickle. Compatible mode is Fory's schema-evolution mode. It writes the metadata readers and writers need to tolerate schema differences. It is the default for xlang mode and native mode in implementations that expose the option. Use compatible mode when services deploy independently or when fields may be added or deleted over time. Set compatible mode to `false` only when every reader and writer always uses the same schema and you want faster serialization and smaller size. For xlang payloads, set compatible mode to `false` only after verifying that every language uses the same schema, or when native types are generated from Fory schema IDL. For xlang, all peers must agree on type identity. Name-based registration is easier to read in examples. Numeric IDs are smaller and faster, but they require coordination across every reader and writer. ## Cross-Language Serialization Xlang mode writes the cross-language Fory wire format. Bytes produced by one language implementation can be read by another when every peer uses the same type identity, compatible mode setting, and field schema. **Java** ```java import org.apache.fory.Fory; public class Example { public static class Person { public String name; public int age; } public static void main(String[] args) { Fory fory = Fory.builder().withXlang(true).build(); fory.register(Person.class, "example.Person"); Person person = new Person(); person.name = "Alice"; person.age = 30; byte[] bytes = fory.serialize(person); Person decoded = (Person) fory.deserialize(bytes); System.out.println(decoded.name); } } ``` **Python** ```python from dataclasses import dataclass import pyfory @dataclass class Person: name: str age: pyfory.Int32 fory = pyfory.Fory(xlang=True) fory.register_type(Person, name="example.Person") data = fory.serialize(Person("Alice", 30)) person = fory.deserialize(data) print(person.name) ``` **Go** ```go package main import ( "fmt" "github.com/apache/fory/go/fory" ) type Person struct { Name string Age int32 } func main() { f := fory.New(fory.WithXlang(true)) if err := f.RegisterStructByName(Person{}, "example.Person"); err != nil { panic(err) } data, _ := f.Serialize(&Person{Name: "Alice", Age: 30}) var person Person if err := f.Deserialize(data, &person); err != nil { panic(err) } fmt.Println(person.Name) } ``` **Rust** ```rust use fory::{Error, Fory, ForyStruct}; #[derive(ForyStruct, Debug, PartialEq)] struct Person { name: String, age: i32, } fn main() -> Result<(), Error> { let mut fory = Fory::builder().xlang(true).build(); fory.register_by_name::("example.Person")?; let bytes = fory.serialize(&Person { name: "Alice".to_string(), age: 30, })?; let person: Person = fo