Installation

Install

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

Package Install Pick this if

Package	Install	Pick this if
`arcadedb` (native, the default)	`pip install arcadedb` `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)	`pip install arcadedb-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`.

arcadedb (native, the default)

pip install arcadedb
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)

pip install arcadedb-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.

Transition note. The first release of this layout is 26.11.1. Until arcadedb passes its readiness bar, it may appear only as pre-releases, 26.11.1.devN. Until a final 26.11.1 exists, PyPI holds only these pre-releases, and a plain pip install arcadedb or uv add arcadedb installs the newest one. After a final release, a plain install takes the final, and a later pre-release needs pip install --pre arcadedb or 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. A last arcadedb-embedded release will install arcadedb, not 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 pip installs for you. 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, so pip says that no version fits instead of building JPype from source. 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 pip 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

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`

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

macOS Apple Silicon

macosx_11_0_arm64

Windows x86_64

win_amd64

Each native wheel is about 38 MB. These platforms are not built, and pip 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. pip then says No matching distribution found (for a wheel file you downloaded: is not a supported wheel on this 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 and, from 26.11.1, the Studio web UI. They cost nothing at run time until you call create_server().
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).

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.dev2, and arcadedb-jvm prints Backend: jvm):

ArcadeDB Python bindings version: 26.11.1.dev2
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, jvm_kwargs and the flags below do not exist there. 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"))

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"))

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.

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, jvm_kwargs and the flags in JVM options (arcadedb-jvm only) do not exist.
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?.
Base image. Use a glibc-based image, for example python:3.12-slim. Alpine and other musl-based images have no wheel. See Requirements.