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) | |
|---|---|---|
What it is |
The ArcadeDB engine, running inside your Python process. |
Python clients of an ArcadeDB server: |
Needs a server? |
No. An in-process HTTP server and Studio are optional ( |
Yes: the official Docker image |
Package and import name |
|
|
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 |
|---|---|---|
|
The native build. The engine is compiled by GraalVM Community Edition into a shared library, which Python loads with |
Embedded use in scripts, notebooks, tests, CLIs, serverless functions and agents. It starts fast and holds little memory, because there is no 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 ( |
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) |
|
|---|---|---|
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 |
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. |
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, |
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 |
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 ( |
Not available. They raise |
Available. |
JVM options ( |
|
Available. See JVM options. |
A few API calls |
None, except the Java-object calls above, which raise |
Work. |
Both packages run the same ArcadeDB engine, with the same SQL and openCypher and the same database format.
The engine of 26.11.1.post4
The engine of 26.11.1.post4 is the engine of 26.11.1 on both packages. Only the bindings changed. The check compared the Linux x86_64 wheels of 26.11.1.post4, as published on PyPI, with the published 26.11.1 wheels (read on 2026-11-16).
-
arcadedb-jvm: all 70 engine jars of the wheel are the same files as in the 26.11.1 wheel, andarcadedb-engine-26.11.1.jarcarries the same build number in both (a3a5d124572608412aa187f9c4b290e071699473). Only the jar of the bindings,arcadedb-python-bridge.jar, differs. -
arcadedb: the engine inside the library has the same build number and the same engine version, 26.11.1. The library file is built again for every wheel, so the file differs, and so does the source commit of the bindings (e83947e646614bd43f149a8ea0054c8f682dcf11for post4, the commit of the tag).
Two builds of the same source can differ in speed on one operation, so a figure that moves between two wheels of the same source is not by itself a change of the code (ArcadeData/arcadedb-python#404).
The single-record UPDATE through command() is slower in a paper cell on the published 26.11.1.post3 native wheel than on 26.11.1 (ArcadeData/arcadedb-python#400). The cause is the build of that wheel, not the bindings source: the wheel that CI built from the same commit runs the statement as fast as 26.11.1 (the table and the proposed process change are in #404). #400 stays open until a post4 native wheel has been measured in that cell on the mini.
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 |
|---|---|---|
|
Formerly |
The same JVM build, with the import name |
|
Formerly |
The same build, now with the import name |
Migrate from the old names
-
Remove the old package:
uv remove arcadedb-embedded, oruv remove arcadedb-embedded-nativeif that is the one you have. -
Install the new one:
uv add arcadedb-jvmif you usedarcadedb-embedded, oruv add arcadedbif you usedarcadedb-embedded-native. -
Change the import:
import arcadedb_embeddedandimport arcadedb_nativeboth becomeimport 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 alsoarcadedb-python. Check which one a tutorial installs before you copy its code.