---
title: "Installation"
---

# Installation

## Rust Library

Add HeliosDB Nano to your `Cargo.toml`:

```toml
[dependencies]
heliosdb-nano = "4"
```

Or via cargo:

```bash
cargo add heliosdb-nano
```

## CLI Tool

Install the command-line interface:

```bash
cargo install heliosdb-nano --locked
```

## Prebuilt Binaries

Self-contained binaries for Linux (x86_64 / aarch64), macOS (arm64) and Windows
(x86_64), each with `SHA256SUMS`, are attached to every
[GitHub Release](https://github.com/HeliosDatabase/HeliosDB-Nano/releases/latest):

```bash
# Latest release tag (pin a specific tag in production)
VER=$(curl -sSf https://api.github.com/repos/HeliosDatabase/HeliosDB-Nano/releases/latest | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p')
curl -sSfL -O "https://github.com/HeliosDatabase/HeliosDB-Nano/releases/download/$VER/heliosdb-nano-$VER-x86_64-unknown-linux-gnu.tar.gz"
tar xzf "heliosdb-nano-$VER-x86_64-unknown-linux-gnu.tar.gz"
./heliosdb-nano --version
```

The binaries need glibc 2.39 or newer (Debian 13, Ubuntu 24.04, Fedora 40,
RHEL 10). On older systems use the container image below or build from source.
`curl -fsSL https://install.heliosdb.com | sh` does the download, checksum
check and install for you.

## Docker

The official multi-arch image (linux/amd64, linux/arm64) is published to
GitHub Container Registry with every release:

```bash
docker run -d --name heliosdb -p 5432:5432 \
  -e HELIOSDB_PASSWORD=change-me \
  -v heliosdb_data:/data \
  ghcr.io/heliosdatabase/heliosdb-nano:latest   # pin a release tag in production

psql "postgresql://postgres:change-me@localhost:5432/postgres?sslmode=require" -c 'SELECT 1'
```

`HELIOSDB_PASSWORD` (or `HELIOSDB_PASSWORD_FILE`) is required: trust auth is
refused on the container's `0.0.0.0` listener. A self-signed TLS certificate is
generated in `/data/tls` on first start. See
[Production Deployment](https://www.heliosdb.com/docs/nano/guides/production_deployment/) for TLS, secrets and
Kubernetes.

## Python (embedded binding)

```bash
pip install heliosdb-nano-embedded
```

```python
import heliosdb_nano
```

The PyPI package is released separately from the engine and currently lags
behind it. To use the current engine from Python, run `heliosdb-nano start` and
connect over the PostgreSQL wire protocol (e.g. `psycopg2`).

## Other Languages

There is no npm or Go package for Nano. From Node.js, Go, Java, .NET and others,
connect with any PostgreSQL or MySQL driver to a running `heliosdb-nano start`
server, or use the REST API. Client SDKs (Python, TypeScript, Go, Rust) are
maintained as source in [HeliosDB-SDKs](https://github.com/HeliosDatabase/HeliosDB-SDKs)
and are not published to package registries.

## Building from Source

```bash
# Clone repository
git clone https://github.com/HeliosDatabase/HeliosDB-Nano.git
cd HeliosDB-Nano

# Build release (requires Rust 1.85+)
cargo build --release --locked

# Run tests
cargo test
```

## Platform Support

| Platform | Architecture | Result |
|----------|--------------|--------|
| Linux | x86_64, aarch64 | Fully supported |
| macOS | Apple Silicon | Prebuilt binary; x86_64 from source |
| Windows | x86_64 | Prebuilt binary |

Prebuilt Linux binaries require glibc 2.39 or newer; on older distributions
build from source.

## Feature Flags

Enable optional features in `Cargo.toml`:

```toml
[dependencies]
heliosdb-nano = { version = "4", features = ["encryption", "simd"] }
```

| Feature | Description |
|---------|-------------|
| `encryption` | Enable AES-256-GCM encryption at rest |
| `simd` | Enable SIMD acceleration for vector operations |
| `server` | Enable PostgreSQL wire protocol server |
| `vector-search` | HNSW vector indexing (default) |
| `mcp-endpoint` | Built-in MCP endpoint for AI agents |
| `ha-tier1` | Warm-standby / streaming replication (default) |

## Verifying Installation

```bash
# Check version
heliosdb-nano --version

# Run quick test
heliosdb-nano repl --memory
> SELECT 1 + 1;
```

## Next Steps

- [Quick Start Guide](https://www.heliosdb.com/docs/nano/getting-started/quickstart/) - Create your first database
- [Deployment Modes](https://www.heliosdb.com/docs/nano/getting-started/deployment/) - Choose how to deploy