# How to Install Semantica and Its Dependencies: Complete Setup Guide

> Easily install Semantica and its dependencies with pip. Follow our complete setup guide to add core functionality and optional extras for your specific workload. Get started now.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-09

---

**Install the core library with `pip install semantica` and add specific capabilities via optional extras like `semantica[documents]` or `semantica[all]` depending on your workload.**

Semantica is a modular Python library for knowledge graphs and semantic AI maintained in the `semantica-agi/semantica` repository. This guide covers how to install Semantica and its dependencies using the layered installation strategy defined in [`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml), ranging from the lightweight core to full production deployments.

## Prerequisites

Before installing Semantica, ensure your environment meets the baseline requirements. The library requires **Python ≥ 3.9.2** because some core dependencies (such as `numpy`) no longer publish wheels for older patch versions. Using a virtual environment is strongly recommended to avoid version conflicts with system packages:

```bash
python -m venv .venv
source .venv/bin/activate  # on Windows: .venv\Scripts\activate

```

## Install the Core Library

The **core installation** provides the graph engine, provenance tracking, reasoning capabilities, and CLI with only 22 essential dependencies. According to the `semantica-agi/semantica` source code, these packages are declared under `[project.dependencies]` in **[`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml)** (lines 48‑96).

Install the core using pip:

```bash
pip install semantica

```

This command pulls in foundational packages including `numpy`, `pandas`, `scikit-learn`, `rdflib`, `networkx`, `requests`, and `pydantic`. The core contains no heavy ML or visualization stacks, keeping the installation fast and lightweight.

## Add Optional Features with Extras

Semantica uses a granular extra system defined under `[project.optional-dependencies]` in **[`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml)**. Install specific capabilities using the `semantica[extra-name]` syntax to avoid bloating your environment with unnecessary dependencies.

### Document Processing

To parse DOCX, XLSX, PDF, and HTML files, install the `documents` extra. This group is defined on lines 27‑33 of **[`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml)**:

```bash
pip install "semantica[documents]"

```

### Embeddings and Local Models

For local embedding generation without external API calls, use the `embeddings-local` extra, which includes `sentence-transformers`, `fastembed`, and `onnxruntime`. For HuggingFace model support, add `models-huggingface`:

```bash

# Local embeddings only

pip install "semantica[embeddings-local]"

# With HuggingFace integration

pip install "semantica[models-huggingface]"

```

### Vector Store Backends

Connect to vector databases by installing the specific backend extra. Options include in-memory FAISS or hosted solutions like Qdrant and Pinecone:

```bash

# In-memory FAISS

pip install "semantica[vectorstore-faiss]"

# All supported vector stores (Qdrant, Pinecone, Weaviate, etc.)

pip install "semantica[vectorstore-all]"

```

### Graph Database Connectors

Integrate with property graph databases using labeled extras for each backend:

```bash
pip install "semantica[graph-neo4j]"        # Neo4j LPG store

pip install "semantica[graph-falkordb]"     # FalkorDB + Redis

pip install "semantica[graph-amazon-neptune]"  # AWS Neptune

pip install "semantica[graph-apache-age]"   # Apache AGE (PostgreSQL)

```

### Database Ingestion

For enterprise data sources, install specific database connectors:

```bash
pip install "semantica[db-snowflake]"      # Snowflake

pip install "semantica[db-databricks]"     # Databricks Unity Catalog

pip install "semantica[ingest-sap]"        # SAP OData

pip install "semantica[ingest-parquet]"    # Parquet / PyArrow

```

### Install All Extras

For demonstrations or local experimentation, install the complete bundle:

```bash
pip install "semantica[all]"

```

## Verify the Installation

After installation, run the built-in health check to confirm which components are available:

```bash
semantica doctor

```

This command prints a status report indicating whether core dependencies are satisfied and which optional extras are detected (e.g., `✔ graph-neo4j available` or `✖ vectorstore-faiss missing`).

## Install From Source

Contributors and users requiring the latest unreleased changes should install from the GitHub repository. The README documents this workflow starting at line 69.

Clone the repository and install in editable mode with development dependencies:

```bash
git clone https://github.com/semantica-agi/semantica.git
cd semantica
pip install -e ".[dev]"
pytest tests/

```

The `dev` extra includes testing frameworks and build tools required for contributing to the codebase.

## Deploy with Docker

For production environments, use the provided **Dockerfile** instead of direct pip installation. The container build process (lines 34‑75) installs the core from [`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml) and then adds specific extras using pinned lockfiles ([`explorer-extra-py313.txt`](https://github.com/semantica-agi/semantica/blob/main/explorer-extra-py313.txt) and [`pep517-build.txt`](https://github.com/semantica-agi/semantica/blob/main/pep517-build.txt)) to ensure reproducible builds.

Build and run the Explorer UI:

```bash
docker build -t semantica:latest .
docker run -p 8000:8000 semantica:latest

```

## Summary

- **Core installation**: `pip install semantica` provides the graph engine and CLI with 22 essential dependencies defined in **[`pyproject.toml`](https://github.com/semantica-agi/semantica/blob/main/pyproject.toml)**.
- **Granular extras**: Use bracket syntax (e.g., `semantica[documents]`, `semantica[graph-neo4j]`) to install only the capabilities you need.
- **Verification**: Run `semantica doctor` to check which optional components are available in your environment.
- **Production**: Use the repository's **Dockerfile** with lockfiles for reproducible container deployments rather than direct pip installs.

## Frequently Asked Questions

### What Python version does Semantica require?

Semantica requires **Python 3.9.2 or higher**. The maintainers dropped support for older Python patches because core dependencies like `numpy` no longer provide pre-built wheels for them, which would force lengthy source compilations.

### How do I install only specific features to keep my Docker image small?

Specify individual extras rather than using `[all]`. For example, if you only need Neo4j and document parsing, run `pip install "semantica[graph-neo4j,documents]"`. This approach pulls only the necessary transitive dependencies, reducing your final container size by excluding unused ML frameworks or database drivers.

### How can I verify that optional dependencies installed correctly?

Run the **`semantica doctor`** command after installation. It checks for the presence of each optional extra's underlying packages (like `faiss-cpu` for vector storage or `neo4j` for graph connectivity) and reports which features are active.

### Can I contribute to Semantica and test my changes locally?

Yes. Clone the repository and install in editable mode with `pip install -e ".[dev]"`. This installs the core plus testing dependencies, allowing you to run `pytest tests/` against your modifications. The development install path is documented in the **README.md** under the "From source" section.