Installation

Install

Pick one of the two packages. Both import as arcadedb. If you are not sure, take arcadedb.

Package Install Pick this if

arcadedb (native, the default)

uv add arcadedb

You write scripts, notebooks, tests, CLIs, serverless functions or agents. You want a fast start and a small footprint, and you need no JVM.

arcadedb-jvm (JVM)

uv add arcadedb-jvm

Your load is heavy and long-running, so the JIT compiler pays off. Or you need the Java-object APIs, JVM options, jvm_kwargs or start_jvm.

Install one of them, not both. If both are installed, import arcadedb raises an ImportError that names both packages. See Which package? for the comparison, and for how to switch.

Both packages run the engine inside your Python process. If you want a client for a running ArcadeDB server instead, install a driver (arcadedb-driver or arcadedb-driver-grpc): see Embedded bindings or a driver?.

First release. The first release of this layout is 26.11.1, and both packages have a final release on PyPI. A plain uv add arcadedb installs the final, and a later pre-release (A.B.C.devN) needs uv add --prerelease allow arcadedb. The same holds for arcadedb-jvm.
Old names. The JVM package was formerly arcadedb-embedded. It is now arcadedb-jvm, the same build. The native package was formerly arcadedb-embedded-native. It is now arcadedb, and the old project is archived. The last arcadedb-embedded release, 26.11.1, is a shim that installs arcadedb and warns once at import. It does not install arcadedb-jvm. See Old names.

The JVM package is self-contained. It carries a Java 25 runtime for its platform, so you do not install Java. Its only Python dependency is JPype1 1.5.0 or later (the Java-Python bridge), which uv add installs with it. The native package needs no Java and no JPype. Optional extras install the columnar helpers of the native package: [numpy], [arrow], [pandas] and [polars].

Requirements

  • Python 3.11 to 3.14 for both packages. The native package also supports Python 3.15: it is one py3-none wheel that loads its library with ctypes, and the CI runs a subset of the tests on 3.15. arcadedb-jvm does not install on 3.15 yet, because its dependency JPype has no 3.15 wheel: its requires-python is >=3.11,<3.15, but uv does not stop at that upper bound and fails while building JPype from source, so use Python 3.14 or older for it. The cap goes when JPype ships a 3.15 wheel. The CI tests the JVM wheel on all four versions 3.11 to 3.14 on Linux x86_64, and on 3.11 and 3.14 on the other platforms (Continuous integration).

  • One of the four platforms below. The Windows wheel of the native build is the newest, and its test run is the least proven of the four. It needs the Microsoft Visual C++ runtime (VCRUNTIME140.dll), which every CPython for Windows already brings.

Every wheel is platform-specific and built on a native runner of its platform, so the installer needs no hint to pick the right one. Each package is one file for each platform, tagged py3-none-<platform>, and it serves every Python version it supports. The native wheel does so because it loads its library with ctypes. The JVM wheel carries a JRE for its platform, and nothing in it is compiled against CPython: JPype, its dependency, has its own wheel for each Python version.

Platform Platform tag, arcadedb Platform tag, arcadedb-jvm

Linux x86_64

manylinux_2_28_x86_64: glibc 2.28 or later (RHEL 8 and Rocky 8, Debian 10, Ubuntu 20.04 and newer)

manylinux_2_28_x86_64: glibc 2.28 or later

Linux ARM64

manylinux_2_28_aarch64: glibc 2.28 or later

manylinux_2_28_aarch64: glibc 2.28 or later

macOS Apple Silicon

macosx_11_0_arm64

macosx_11_0_arm64

Windows x86_64

win_amd64

win_amd64

Each native wheel is about 66 MB. These platforms are not built, and the installer finds no wheel for them:

  • Intel Macs (macOS x86_64). Apple has sold only Apple Silicon Macs since 2023, and macOS 26 is the last release for Intel Macs. On an Intel Mac, run the Linux wheel in Docker or in a Linux virtual machine.

  • Alpine Linux and other musl-based distributions. The Linux wheels are for glibc, so the installer reports that no wheel matches the platform. Use a glibc image, for example python:3.12-slim.

  • Windows on ARM.

  • Linux with an older glibc than the table, for example Amazon Linux 2 and CentOS 7.

What is included

  • The ArcadeDB engine with all models (graph, document, key/value, vector, time series) and both query languages, SQL and openCypher.

  • Vector indexes, and data import for CSV, XML and ArcadeDB JSONL.

  • The optional in-process HTTP server, which costs nothing at run time until you call create_server(). In the JVM package, from 26.11.1, it also serves the Studio web UI. The native package has no Studio.

  • In the JVM package: a bundled Java 25 runtime, trimmed with jlink. In the native package: the engine as a GraalVM native-image shared library.

Engine modules the bindings do not use are left out to keep the wheel small. These include the gRPC and MongoDB wire protocols, Raft HA, and Gremlin.

JavaScript is not available. The GraalJS jars are left out, so DEFINE FUNCTION …​ LANGUAGE js fails. Define functions in SQL or openCypher, or register a Python function with Database.register_function (it works on both packages, see Python functions and record events).
The Studio web UI is in the JVM wheels from 26.11.1. Studio used to bundle ApexCharts, which is no longer open source (ArcadeData/arcadedb#10579). ArcadeData/arcadedb#10627 replaced it with Apache ECharts. The earlier 26.10.x wheels on PyPI do not contain Studio. The HTTP API of the in-process server works in all of them.

Verify the installation

The script works with both packages. arcadedb.backend tells you which one runs: native or jvm.

import arcadedb
print(f"ArcadeDB Python bindings version: {arcadedb.__version__}")
print(f"Backend: {arcadedb.__backend__}")

# Test database creation
with arcadedb.create_database("./test") as db:
    result = db.query("sql", "SELECT 1 as test")
    print(f"Database working: {result.first().get('test') == 1}")

Run in an empty directory, the script prints (the version and the backend match what you installed; this output is from arcadedb 26.11.1, and arcadedb-jvm prints Backend: jvm):

ArcadeDB Python bindings version: 26.11.1
Backend: native
Database working: True

The engine also writes log lines to the standard error stream. The output on this page shows the standard output only.

JVM options (arcadedb-jvm only)

The native package has no JVM, so start_jvm and the flags below do not exist there, and jvm_kwargs is accepted and ignored: create_database and open_database log a warning that names the keys and go on. With arcadedb-jvm, configure the bundled JVM inside Python, before the first database is created:

import arcadedb
from arcadedb.jvm import start_jvm

# Configure the JVM once per process, before the first database is created
start_jvm(heap_size="2g", jvm_args="-XX:MaxDirectMemorySize=2g")

with arcadedb.create_database("./jvmdb") as db:
    print(db.query("sql", "SELECT 1 AS one").first().get("one"))
1

Or pass the options when you create or open a database:

import arcadedb

with arcadedb.create_database("./jvmdb2", jvm_kwargs={"heap_size": "2g"}) as db:
    print(db.query("sql", "SELECT 1 AS one").first().get("one"))
1

Two kinds of flag go in jvm_args:

  • -X and -XX flags are JVM runtime options, such as -Xmx<size> for the maximum heap and -XX:MaxDirectMemorySize=<size> for off-heap buffers.

  • -D flags are system properties that configure ArcadeDB.

One JVM configuration per process. JVM options are locked after the JVM starts. Call start_jvm(…​) or pass jvm_kwargs before the first database is created. To change the settings, start a new Python process.

Each Python process starts its own JVM, and each JVM sees the whole container limit. With several Python processes in one container, give each process its own heap_size.

Class-data sharing

The bundled JRE ships the JVM’s default class-data-sharing archive, dumped with -XX:+UseCompactObjectHeaders, the flag that start_jvm sets. The JVM finds the archive by itself and maps the JDK’s classes from it instead of loading and verifying them at every start. You do nothing to use it. The JVM ignores the archive, and starts as it did before, when your jvm_args change a setting that the archive depends on (-XX:-UseCompactObjectHeaders, -Xshare:off) or when the heap is larger than 32 GB (the default is half of the RAM, so a machine with more than 64 GB of RAM starts without the archive unless you set heap_size). The archive holds the JDK’s classes only, not the engine’s jars. It is a file in the bundled JRE (about 15 MB, about 3.9 MB inside the wheel), so each JVM wheel is larger by that much. The native package has no JVM and no archive.

Faster start-up with the AOT cache

JDK 25 can keep an ahead-of-time (AOT) cache of the classes it loads and links at start-up (Project Leyden: the cache is JEP 483, the one-step training run that writes it is JEP 514). A later JVM start then skips that work. The arcadedb-jvm package supports it and keeps it off by default. Turn it on with the environment variable ARCADEDB_AOT=1, or with start_jvm(aot=True) before the first database is created. The argument wins over the variable, so aot=False turns it off even when the variable is set.

from arcadedb.jvm import start_jvm

start_jvm(aot=True)   # the same as ARCADEDB_AOT=1 in the environment

How it works. The first process on a machine trains the cache: the JVM writes the file when that process exits normally. The next start checks the file with the bundled JVM and then uses it. The file is in your per-user cache directory ($XDG_CACHE_HOME/arcadedb/aot or ~/.cache/arcadedb/aot on Linux). Set ARCADEDB_AOT_CACHE=<file> to name the file yourself. The cache records the jars it was made for, so each package version trains its own file. Any problem (a directory you cannot write, a full disk, a file the JVM refuses) gives a normal start. The same holds when your jvm_args carry their own -XX:AOT* or -Xshare flags: the package then adds nothing.

When to turn it on

Turn it on for short-lived processes, where the JVM start and the first queries are a large part of the run time: command-line tools, scripts, test runs and jobs that start often. Keep the cache directory between runs. A file system that is empty at every start trains again each time and pays the one-time cost each time.

Do not bother with it for a long-running service. The cache changes the start only, and the measurement below shows no steady-state gain that we can rely on. If start-up time matters most and you can choose the package, arcadedb has no JVM to start (see Which package?).

One-time costs

  • A training run. In the study below, the training process took 4.5 s, against 2.8 s for the same program without the cache.

  • One check run. The next start runs the bundled JVM once more to check the new file (0.7 s in the study).

  • Disk. The cache file was 41,529,344 bytes (39.6 MiB).

What we measured

One study, on one laptop (Linux x86_64), with arcadedb-jvm 26.11.1.dev0 on its bundled JDK 25. Each figure is the ratio of the time with ARCADEDB_AOT=1 to the time without it, so a value below 1 means faster with the cache. The runs alternated between the two settings (ABBA order), 19 rounds each, and each figure has 18 clean pairs. The table gives the median ratio and its 95% interval. A control arm that repeated the setting without the cache gave an interval that includes 1 for each of the five figures that the study had to decide on, which is the check that the method does not invent a difference.

  • First script (the first five rows of the table): a new process on an existing graph database of 5,000 vertices and 15,000 edges. It imports the package, starts the JVM, opens the database, runs one SQL query by id and runs one openCypher 2-hop query. Each round takes the median of 5 new processes.

  • Steady (the last four rows of the table): one process that inserts 300,000 documents with insert_many (unique index, commit_every=5000), makes 100,000 point reads, and runs 5,000 openCypher 2-hop queries on a graph of 20,000 vertices and 60,000 edges after 500 warm-up queries.

Figure Median ratio 95% interval

First script, from import to the first openCypher result

0.653

[0.648, 0.658]

Opening the database

0.482

[0.475, 0.489]

First SQL query

0.579

[0.562, 0.590]

First openCypher query

0.455

[0.431, 0.489]

JVM start (start_jvm())

0.921

[0.911, 0.930]

Steady: insert_many of 300,000 documents

1.000

[0.948, 1.036]

Steady: 100,000 point reads

0.931

[0.877, 1.002]

Steady: 5,000 warm 2-hop openCypher queries

0.943

[0.902, 0.996]

Steady: peak memory (RSS)

1.009

[0.940, 1.074]

The first script ran about a third faster with the cache (ratio 0.653, interval [0.648, 0.658]), and the gain is in opening the database and in the first queries. The steady rows show at most a small gain: the interval of the 2-hop queries ends just below 1, and the intervals of the insert, the point reads and the memory include 1. The interval of the insert reaches 1.036. This is why the cache stays opt-in. These figures come from one machine and one workload. Measure on your own before you rely on them.

Native build notes (arcadedb)

The native package is the same engine compiled to a GraalVM native-image shared library. It needs no JVM and no JPype, so the JVM options above do not apply to it. The calls that hand out a Java object (get_java_database, get_java_document) raise NotOnNativeYet (a NotImplementedError) instead of misbehaving. The list is in Which package?. Report problems in the issue tracker and say which package you use.

Heap size

The engine runs in a GraalVM isolate. By default the native package limits its heap to 50% of the memory the process can see. It does this with the isolate argument -XX:MaximumHeapSizePercent=50. The GraalVM default is 80%. The engine also uses memory outside the heap. With 80%, the kernel killed the process in containers that have a memory limit. With 50%, the same cases ran clean, and the timings of the benchmark figures did not change by more than the noise.

The percentage follows the container memory limit (the cgroup limit) when there is one. Without a limit it follows the memory of the host. In a container with a 4 GB limit, the heap limit is 2 GB.

To set the heap yourself, put one of these arguments in the environment variable ARCADEDB_NATIVE_ISOLATE_ARGS before the first database is opened. The variable takes space-separated arguments:

export ARCADEDB_NATIVE_ISOLATE_ARGS="-Xmx2g"                        # a fixed maximum heap
export ARCADEDB_NATIVE_ISOLATE_ARGS="-XX:MaximumHeapSizePercent=70"  # another percentage
export ARCADEDB_NATIVE_ISOLATE_ARGS="-XX:MaxRAM=4g"                 # a memory size for the percentage; GraalVM's 80% applies to it

When one of these three is present, the package adds no default. Do not use -XX:MaxRAMPercentage. The native image does not accept it, and the isolate then fails to start with graal_create_isolate failed (rc=22). The same variable also takes the engine’s -D settings: see Where the logs go. For what a native image build supports, see Native image in the main ArcadeDB docs.

Limits of the native build

What the native package cannot do, or does differently from arcadedb-jvm. Read this before you pick it for a production service.

  • Serial garbage collector. GraalVM Community Edition offers one garbage collector for native images, the serial one (the G1 collector is part of Oracle GraalVM only). A collection stops all threads, and its pause grows with the amount of live data. For a heavy, long-running load, a large heap or many busy threads, use arcadedb-jvm.

  • Heap limit of 50% by default. The package sets -XX:MaximumHeapSizePercent=50, so the process holds at most half of the memory it can see. See Heap size to change it.

  • No Java objects, no JVM options. get_java_database, get_java_document and the other get_java_* calls raise NotOnNativeYet. start_jvm and the flags in JVM options (arcadedb-jvm only) do not exist, and jvm_kwargs is ignored with a logged warning.

  • No console log on Windows by default. The log goes to the file only. See Where the logs go for the reason and for ARCADEDB_LOG_CONSOLE.

  • Engine modules left out. The gRPC and MongoDB wire protocols, Raft HA, Gremlin and the polyglot languages (JavaScript, Python as a query language) are not in the image. See What is included.

  • Platforms. Intel Macs, Alpine Linux (musl) and Windows on ARM have no wheel. See Requirements.

In a container

The facts that matter in a container are spread over several pages. This list collects them.

  • Memory limit. arcadedb limits its heap to 50% of the container memory limit (the cgroup limit), and the engine also uses memory outside the heap. See Heap size. Each arcadedb-jvm process starts its own JVM, and each JVM sees the whole container limit. With several Python processes in one container, give each its own heap_size. See JVM options (arcadedb-jvm only).

  • Transaction size. A bulk load holds the rows of a transaction in memory until it commits, so a smaller commit size lowers the heap a load needs. See Bulk loads and commit size.

  • Read-only file systems. Neither package writes into the working directory. The log goes to a per-user state directory. When that directory cannot be written, the package logs a warning and uses a new directory under the system temp directory. To keep the log, set ARCADEDB_LOG_DIR to a writable volume. See Where the logs go. The database directory itself must be on a writable volume.

  • Start-up. arcadedb has no JVM to start, so processes that start often, such as serverless functions and short jobs, start faster with it. See Which package?. With arcadedb-jvm, the opt-in AOT cache shortens the start: see Faster start-up with the AOT cache.

  • Base image. Use a glibc-based image, for example python:3.12-slim. Alpine and other musl-based images have no wheel. See Requirements.