Which package?

Two packages give you the ArcadeDB engine inside your Python process. Both use the import name arcadedb, and they have the same public API. Install one of them, not both. If you are not sure that you want the engine in your process at all, read the next section first.

Embedded bindings or a driver?

Python reaches ArcadeDB in two different ways, and the names look alike. The embedded bindings (this repository) run the engine inside your Python process. The official drivers (developed in ArcadeData/arcadedb-drivers) are clients that talk to a running ArcadeDB server. A driver contains no engine.

Embedded bindings (this repository) Drivers (ArcadeData/arcadedb-drivers)

	Embedded bindings (this repository)	Drivers (ArcadeData/arcadedb-drivers)
What it is	The ArcadeDB engine, running inside your Python process.	Python clients of an ArcadeDB server: `arcadedb-driver` over HTTP (sync and async) and `arcadedb-driver-grpc` over gRPC. They contain no engine.
Needs a server?	No. An in-process HTTP server and Studio are optional (`create_server()`).	Yes: the official Docker image `arcadedata/arcadedb`, or any ArcadeDB server. The gRPC driver also needs the gRPC plugin of the server, enabled with `-Darcadedb.server.plugins=Grpc:com.arcadedb.server.grpc.GrpcServerPlugin`.
Package and import name	`arcadedb` (native, the default) or `arcadedb-jvm` (JVM). Both: `import arcadedb`.	`arcadedb-driver`: `import arcadedb_driver`. `arcadedb-driver-grpc`: `import arcadedb_driver_grpc`.
Use it when	You need no server: one process, tests, notebooks, scripts, or an agent that owns its data.	Several clients share the data, a server already exists, you want a service boundary, or some clients are not written in Python.

What it is

The ArcadeDB engine, running inside your Python process.

Python clients of an ArcadeDB server: arcadedb-driver over HTTP (sync and async) and arcadedb-driver-grpc over gRPC. They contain no engine.

Needs a server?

No. An in-process HTTP server and Studio are optional (create_server()).

Yes: the official Docker image arcadedata/arcadedb, or any ArcadeDB server. The gRPC driver also needs the gRPC plugin of the server, enabled with -Darcadedb.server.plugins=Grpc:com.arcadedb.server.grpc.GrpcServerPlugin.

Package and import name

arcadedb (native, the default) or arcadedb-jvm (JVM). Both: import arcadedb.

arcadedb-driver: import arcadedb_driver. arcadedb-driver-grpc: import arcadedb_driver_grpc.

Use it when

You need no server: one process, tests, notebooks, scripts, or an agent that owns its data.

Several clients share the data, a server already exists, you want a service boundary, or some clients are not written in Python.

A rule of thumb:

No server and one process (tests, notebooks, scripts, an agent that owns its data): use the embedded bindings.
Several clients, an existing server, a service boundary, HA or replication, or clients in other languages: use a driver.
You can use both. For example, run a job with the embedded bindings, and let other programs reach a shared server through the HTTP driver.

The name arcadedb on PyPI is the embedded package, and the driver is arcadedb-driver. So uv add arcadedb gives you the engine, and uv add arcadedb-driver gives you a client that needs a server.

The package formerly arcadedb-embedded is now a shim that installs arcadedb (see Old names).

The driver pages of the main manual: Python HTTP driver, Python gRPC driver, Native drivers and the Python quickstart. The manual page for the embedded bindings is Python embedded.

The server also speaks the Bolt, PostgreSQL, MongoDB and Redis protocols, for compatibility with existing tools. You reach them with the standard clients (neo4j, psycopg, pymongo, redis-py). ArcadeDB has no client of its own for these four. See API and integration, Neo4j Bolt, PostgreSQL protocol, MongoDB and Redis.

Native build or JVM build

If you chose the embedded bindings, pick the build.

Package Engine Pick it for

Package	Engine	Pick it for
`arcadedb` (the default)	The native build. The engine is compiled by GraalVM Community Edition into a shared library, which Python loads with `ctypes`. No JVM, no JPype, no bundled Java runtime.	Embedded use in scripts, notebooks, tests, CLIs, serverless functions and agents. It starts fast and holds little memory, because there is no JVM.
`arcadedb-jvm`	The JVM build. The Java engine runs in your process through JPype, on a bundled Java 25 runtime.	Heavy, long-running loads, where the JIT compiler makes the engine faster over time, and vector search where index build and query speed matter more than memory (see [vector-search]). Also the Java-object APIs (`get_java_database` and similar), JVM options, `jvm_kwargs` and `start_jvm`.

arcadedb (the default)

The native build. The engine is compiled by GraalVM Community Edition into a shared library, which Python loads with ctypes. No JVM, no JPype, no bundled Java runtime.

Embedded use in scripts, notebooks, tests, CLIs, serverless functions and agents. It starts fast and holds little memory, because there is no JVM.

arcadedb-jvm

The JVM build. The Java engine runs in your process through JPype, on a bundled Java 25 runtime.

Heavy, long-running loads, where the JIT compiler makes the engine faster over time, and vector search where index build and query speed matter more than memory (see [vector-search]). Also the Java-object APIs (get_java_database and similar), JVM options, jvm_kwargs and start_jvm.

uv add arcadedb     # native, the default
uv add arcadedb-jvm        # JVM, for heavy long-running loads

If you are not sure, install arcadedb. You can switch later: your code does not change (see Switch from one to the other).

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. The readiness bar for the native build is listed in Release.

Check which one you have

python -c "import arcadedb; print(arcadedb.__backend__)"

It prints native or jvm. You can also ask uv:

uv tree --depth 1

uv tree --depth 1 lists the direct dependencies of your project. In a correct environment exactly one of arcadedb and arcadedb-jvm is among them.

What changes between them

The API is the same. The runtime is not. These are the differences you can plan for.

arcadedb (native) arcadedb-jvm (JVM)

	`arcadedb` (native)	`arcadedb-jvm` (JVM)
Start-up	Fast. There is no JVM to start.	Slower. Every Python process starts a JVM first. The opt-in AOT cache shortens the start (Faster start-up with the AOT cache).
Memory	Small footprint.	Larger. The JVM keeps a heap, and each Python process starts its own JVM.
Garbage collector	The serial collector of GraalVM Community Edition. A collection stops all threads, and the pause grows with the live data. The heap limit is 50% of the memory by default (Heap size).	The JVM’s own collectors, G1 by default on a server-class machine. You choose them and the heap with `jvm_kwargs` (JVM options).
Throughput on long loads	No JIT warm-up. Speed over a long run depends on the workload.	The JIT compiler makes long-running loads faster over time.
Speed on your data	Measure on your own workload.	Measure on your own workload.
Vector search (`LSM_VECTOR`)	Slower to build and to query, smaller in memory. Against the JVM build, index builds took 1.28 to 1.62 times as long and median queries 1.22 to 1.87 times as long, and peak memory was 0.51 to 0.67 of the JVM build’s (medians, 100,000 vectors of 128, 768 and 1536 dimensions, `26.11.1.dev0`, one laptop, measured before the change that makes native `find_nearest` send its query as one `float32` buffer (#203), with the Highway kernels that are the default on Linux, see Distance kernels in the native package).	Faster to build and to query, larger in memory.
Wheel size	Smaller. It carries no Java runtime. The library inside is built with GraalVM Community Edition at `-O3`: about 1.6 times the size of an `-O2` build, for a measured warm speedup over it (geometric mean of the warm timings 0.736 of the `-O2` time).	Larger. It carries a Java 25 runtime for its platform.
Python versions	3.11 to 3.15. On 3.15 the CI runs a subset of the tests.	3.11 to 3.14. JPype has no 3.15 wheel yet, so the package does not install on 3.15: uv tries to build JPype from source and fails.
Platforms	Linux x86_64 and aarch64 (glibc 2.28 or later), macOS arm64, Windows x64. The Windows wheel is the newest: it is built in CI, and its test run is the least proven of the four. Not built: Intel Mac, Alpine (musl), Windows on ARM. See Requirements.	Linux x86_64 and aarch64 (glibc 2.28 or later), macOS arm64, Windows x64. Not built: Intel Mac, Alpine (musl), Windows on ARM.
Java-object APIs (`get_java_database`, `get_java_document`, `get_java_*`)	Not available. They raise `NotOnNativeYet`.	Available.
JVM options (`jvm_kwargs`, `start_jvm`, `-X` and `-D` flags)	`start_jvm` and the `-X` and `-D` flags do not exist, because there is no JVM. `jvm_kwargs` is accepted and ignored, with a logged warning.	Available. See JVM options.
A few API calls	None, except the Java-object calls above, which raise `NotOnNativeYet` (a `NotImplementedError`).	Work.

Start-up

Fast. There is no JVM to start.

Slower. Every Python process starts a JVM first. The opt-in AOT cache shortens the start (Faster start-up with the AOT cache).

Memory

Small footprint.

Larger. The JVM keeps a heap, and each Python process starts its own JVM.

Garbage collector

The serial collector of GraalVM Community Edition. A collection stops all threads, and the pause grows with the live data. The heap limit is 50% of the memory by default (Heap size).

The JVM’s own collectors, G1 by default on a server-class machine. You choose them and the heap with jvm_kwargs (JVM options).

Throughput on long loads

No JIT warm-up. Speed over a long run depends on the workload.

The JIT compiler makes long-running loads faster over time.

Speed on your data

Measure on your own workload.

Vector search (LSM_VECTOR)

Slower to build and to query, smaller in memory. Against the JVM build, index builds took 1.28 to 1.62 times as long and median queries 1.22 to 1.87 times as long, and peak memory was 0.51 to 0.67 of the JVM build’s (medians, 100,000 vectors of 128, 768 and 1536 dimensions, 26.11.1.dev0, one laptop, measured before the change that makes native find_nearest send its query as one float32 buffer (#203), with the Highway kernels that are the default on Linux, see Distance kernels in the native package).

Faster to build and to query, larger in memory.

Wheel size

Smaller. It carries no Java runtime. The library inside is built with GraalVM Community Edition at -O3: about 1.6 times the size of an -O2 build, for a measured warm speedup over it (geometric mean of the warm timings 0.736 of the -O2 time).

Larger. It carries a Java 25 runtime for its platform.

Python versions

3.11 to 3.15. On 3.15 the CI runs a subset of the tests.

3.11 to 3.14. JPype has no 3.15 wheel yet, so the package does not install on 3.15: uv tries to build JPype from source and fails.

Platforms

Linux x86_64 and aarch64 (glibc 2.28 or later), macOS arm64, Windows x64. The Windows wheel is the newest: it is built in CI, and its test run is the least proven of the four. Not built: Intel Mac, Alpine (musl), Windows on ARM. See Requirements.

Linux x86_64 and aarch64 (glibc 2.28 or later), macOS arm64, Windows x64. Not built: Intel Mac, Alpine (musl), Windows on ARM.

Java-object APIs (get_java_database, get_java_document, get_java_*)

Not available. They raise NotOnNativeYet.

Available.

JVM options (jvm_kwargs, start_jvm, -X and -D flags)

start_jvm and the -X and -D flags do not exist, because there is no JVM. jvm_kwargs is accepted and ignored, with a logged warning.

Available. See JVM options.

A few API calls

None, except the Java-object calls above, which raise NotOnNativeYet (a NotImplementedError).

Work.

Both packages run the same ArcadeDB engine, with the same SQL and openCypher and the same database format.

Switch from one to the other

The two wheels refuse to work together. If both are installed, import arcadedb raises an ImportError that names both packages. The reason is that both wheels write into the same arcadedb directory, and the installer would overwrite files of one with files of the other without a message. So remove both and install the one you want:

uv remove arcadedb arcadedb-jvm
uv add arcadedb-jvm

There is no extra to select a build: arcadedb[jvm] does not exist. Your code stays as it is, because both import as arcadedb. Only code that uses a JVM-only API (see the table above) needs a change when you move to the native build.

Server use

Neither package is a server deployment. They embed the engine in one Python process. For HTTP access, Studio, many processes, other programming languages or high availability, run the official Docker image arcadedata/arcadedb and connect with a driver (see Packages that talk to a server). Embedded bindings or a driver? compares the two ways.

Old names

The packages had other names until 26.10.x. Search results and old tutorials may still use them.

New package Old name Note

New package	Old name	Note
`arcadedb-jvm`	Formerly `arcadedb-embedded`, imported as `arcadedb_embedded`	The same JVM build, with the import name `arcadedb`. The last release of the project formerly `arcadedb-embedded` (26.11.1) is a deprecation shim. It installs `arcadedb`, the native build, and warns once at import. If you need the JVM build, install `arcadedb-jvm` yourself.
`arcadedb`	Formerly `arcadedb-embedded-native`, imported as `arcadedb_native`	The same build, now with the import name `arcadedb`. The old preview versions were 26.10.x pre-releases. The old project is archived on PyPI: no new releases and no shim.

arcadedb-jvm

Formerly arcadedb-embedded, imported as arcadedb_embedded

The same JVM build, with the import name arcadedb. The last release of the project formerly arcadedb-embedded (26.11.1) is a deprecation shim. It installs arcadedb, the native build, and warns once at import. If you need the JVM build, install arcadedb-jvm yourself.

arcadedb

Formerly arcadedb-embedded-native, imported as arcadedb_native

The same build, now with the import name arcadedb. The old preview versions were 26.10.x pre-releases. The old project is archived on PyPI: no new releases and no shim.

Migrate from the old names

Remove the old package: uv remove arcadedb-embedded, or uv remove arcadedb-embedded-native if that is the one you have.
Install the new one: uv add arcadedb-jvm if you used arcadedb-embedded, or uv add arcadedb if you used arcadedb-embedded-native.
Change the import: import arcadedb_embedded and import arcadedb_native both become import arcadedb. The builds are the same as in the table above, so the rest of your code stays.

Releases of the new layout start with 26.11.1. The 26.10.x wheels were built in a separate repository of the humemai organisation.

Packages that talk to a server

None of these contains the engine. They connect to a running ArcadeDB server.

arcadedb-driver: the official HTTP client. See Python — HTTP driver.
arcadedb-driver-grpc: the official gRPC client. See Python — gRPC driver.
arcadedb-python: a community HTTP driver by Steve Reiner and others (stevereiner/arcadedb-python). It is not related to this repository, whose name is also arcadedb-python. Check which one a tutorial installs before you copy its code.