Installation Options

Direct Installation

Prerequisites

Morphik requires PostgreSQL with the pgvector extension for vector storage and similarity search capabilities. Follow the installation instructions for your operating system:

On macOS, you can use Homebrew to install PostgreSQL and pgvector:

brew install postgresql@14
brew install pgvector

Start the PostgreSQL service:

brew services start postgresql@14

Create a database and user for Morphik:

createdb morphik
createuser -s postgres

These commands create a database named “morphik” and a superuser named “postgres” that the application will use to connect.

On macOS, you can use Homebrew to install PostgreSQL and pgvector:

brew install postgresql@14
brew install pgvector

Start the PostgreSQL service:

brew services start postgresql@14

Create a database and user for Morphik:

createdb morphik
createuser -s postgres

These commands create a database named “morphik” and a superuser named “postgres” that the application will use to connect.

Install PostgreSQL from the official repositories.We recommend version 14 . Other versions may work, but haven’t been extensively tested!

sudo apt update
sudo apt install postgresql postgresql-contrib

Install pgvector:

sudo apt install postgresql-14-pgvector

Start and enable the PostgreSQL service:

sudo systemctl start postgresql
sudo systemctl enable postgresql

Create a database and user for Morphik:

sudo -u postgres createdb morphik
sudo -u postgres createuser -s postgres

Download and install PostgreSQL from the official website.
During installation, make note of the password you set for the postgres user.
Install pgvector:
- Open pgAdmin (installed with PostgreSQL)
- Connect to your PostgreSQL server
- Right-click on “Extensions” and select “Create > Extension”
- Select “pgvector” from the dropdown and click “Save”
Create a database for Morphik:
- Right-click on “Databases” and select “Create > Database”
- Name it “morphik” and click “Save”

After installation, verify that PostgreSQL is running correctly:

psql -U postgres -c "SELECT version();"

You should see the following output:

 version                                                            
------------------------------------------------------------------------------------------------------------------------------
<Your postgres version and some compilation details>

Some system-level dependencies might be required for processing various document types:

# Install via Homebrew
brew install poppler tesseract libmagic

# Install via Homebrew
brew install poppler tesseract libmagic

# Install via apt
sudo apt-get update
sudo apt-get install -y poppler-utils tesseract-ocr libmagic-dev

For Windows, you may need to install these dependencies manually:

Poppler: Download from poppler for Windows
Tesseract: Download the installer from UB Mannheim
libmagic: This is included in the python-magic-bin package which will be installed with pip

If you encounter database initialization issues within Docker, you may need to manually initialize the schema:

psql -U postgres -d morphik -a -f init.sql

Install Ollama using Homebrew:

brew install ollama

Start Ollama:

ollama serve

Pull a model to use with Morphik (in a new terminal):

ollama pull llama3.2

Install Ollama using Homebrew:

brew install ollama

Start Ollama:

ollama serve

Pull a model to use with Morphik (in a new terminal):

ollama pull llama3.2

Install Ollama using the official installation script:

curl -fsSL https://ollama.com/install.sh | sh

Start Ollama:

ollama serve

Pull a model to use with Morphik (in a new terminal):

ollama pull llama3.2

Download the Ollama installer from the official website.
Run the installer and follow the on-screen instructions.
After installation, Ollama will start automatically.
Open Command Prompt or PowerShell and pull a model:
```
ollama pull llama3.2
```

Cloning the Repository

To get started with Morphik, we need to first setup the server. This involves cloning the repository, installing the dependencies, and the running the server. You are just a few steps away from accurate, agentic RAG over your multi-modal data!

First, let’s clone the repository from GitHub.

git clone https://github.com/morphik-org/morphik-core.git

After cloning the repository, you will notice a morphik-core folder in your current directory.

ls morphik-core

If you see an error like ls: morphik-core: No such file or directory, it means that the repository is not cloned properly. Please try again.

Once you have cloned the repository, navigate into the morphik-core folder.

cd morphik-core

Next, you need to set up a virtual environment called .venv.

Setting Up the Environment

Installing Python Dependencies

While it is not required, we highly recommend using a virtual environment to ensure dependencies from other projects do not conflict with Morphik. You may use managers like uv or poetry, but for this guide, we will use the built-in venv module.

Morphik currently supports Python 3.12 as the latest version. We recommend using Python 3.12 for optimal compatibility.

python3.12 -m venv .venv

Now, you need to activate the virtual environment. The activation command differs based on your operating system.

source .venv/bin/activate

source .venv/bin/activate

.venv\Scripts\activate.bat

.venv\Scripts\Activate.ps1

If you encounter execution policy errors in PowerShell, you may need to run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

After activation, your command prompt should be prefixed with (.venv), indicating that the virtual environment is active. Once your virtual environment is activated, you can install the required dependencies.

pip install -r requirements.txt

Python Dependencies for Document Processing

You may also need additional Python packages or NLTK resources for processing various document types:

# If using Python 3.12+, you might need a specific version of unstructured
pip install unstructured==0.16.10

# Download required NLTK resources
python -m nltk.downloader averaged_perceptron_tagger punkt

Setting up the Server Parameters

At this point, you may want to customize the server - such as use a different model, enable or disable certain features, etc. - you can do so by editing the morphik.toml file.

Morphik now uses a registered models approach, which allows you to define hundreds of different models in one place and reference them throughout your configuration. This makes it easy to mix and match models based on your needs (e.g., smaller models for simpler tasks). You can find more details about configuration here.

Morphik uses environment variables to manage secrets and API keys. In order to ensure that any pre-set keys are available to the server, copy the .env.example file to .env:

cp .env.example .env

In case you’re using external models like OpenAI or Anthropic Claude, you’ll need to edit the .env file with the necessary API keys. Finally, you can run the setup script to install dependencies and setup the database and vector store.

python quick_setup.py

Launching the Server

You are now ready to launch the Morphik server! Just run the following command to start the server.

python start_server.py

You should see the following output:

INFO:     Started server process [15169]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://localhost:8000 (Press CTRL+C to quit)

This means that the server is running on http://localhost:8000. You can now interact with the server using the API or the Python SDK.

Direct Installation

Prerequisites

Morphik requires PostgreSQL with the pgvector extension for vector storage and similarity search capabilities. Follow the installation instructions for your operating system:

On macOS, you can use Homebrew to install PostgreSQL and pgvector:

brew install postgresql@14
brew install pgvector

Start the PostgreSQL service:

brew services start postgresql@14

Create a database and user for Morphik:

createdb morphik
createuser -s postgres

These commands create a database named “morphik” and a superuser named “postgres” that the application will use to connect.

On macOS, you can use Homebrew to install PostgreSQL and pgvector:

brew install postgresql@14
brew install pgvector

Start the PostgreSQL service:

brew services start postgresql@14

Create a database and user for Morphik:

createdb morphik
createuser -s postgres

These commands create a database named “morphik” and a superuser named “postgres” that the application will use to connect.

Install PostgreSQL from the official repositories.We recommend version 14 . Other versions may work, but haven’t been extensively tested!

sudo apt update
sudo apt install postgresql postgresql-contrib

Install pgvector:

sudo apt install postgresql-14-pgvector

Start and enable the PostgreSQL service:

sudo systemctl start postgresql
sudo systemctl enable postgresql

Create a database and user for Morphik:

sudo -u postgres createdb morphik
sudo -u postgres createuser -s postgres

Download and install PostgreSQL from the official website.
During installation, make note of the password you set for the postgres user.
Install pgvector:
- Open pgAdmin (installed with PostgreSQL)
- Connect to your PostgreSQL server
- Right-click on “Extensions” and select “Create > Extension”
- Select “pgvector” from the dropdown and click “Save”
Create a database for Morphik:
- Right-click on “Databases” and select “Create > Database”
- Name it “morphik” and click “Save”

After installation, verify that PostgreSQL is running correctly:

psql -U postgres -c "SELECT version();"

You should see the following output:

 version                                                            
------------------------------------------------------------------------------------------------------------------------------
<Your postgres version and some compilation details>

Some system-level dependencies might be required for processing various document types:

# Install via Homebrew
brew install poppler tesseract libmagic

# Install via Homebrew
brew install poppler tesseract libmagic

# Install via apt
sudo apt-get update
sudo apt-get install -y poppler-utils tesseract-ocr libmagic-dev

For Windows, you may need to install these dependencies manually:

Poppler: Download from poppler for Windows
Tesseract: Download the installer from UB Mannheim
libmagic: This is included in the python-magic-bin package which will be installed with pip

If you encounter database initialization issues within Docker, you may need to manually initialize the schema:

psql -U postgres -d morphik -a -f init.sql

Install Ollama using Homebrew:

brew install ollama

Start Ollama:

ollama serve

Pull a model to use with Morphik (in a new terminal):

ollama pull llama3.2

Install Ollama using Homebrew:

brew install ollama

Start Ollama:

ollama serve

Pull a model to use with Morphik (in a new terminal):

ollama pull llama3.2

Install Ollama using the official installation script:

curl -fsSL https://ollama.com/install.sh | sh

Start Ollama:

ollama serve

Pull a model to use with Morphik (in a new terminal):

ollama pull llama3.2

Download the Ollama installer from the official website.
Run the installer and follow the on-screen instructions.
After installation, Ollama will start automatically.
Open Command Prompt or PowerShell and pull a model:
```
ollama pull llama3.2
```

Cloning the Repository

First, let’s clone the repository from GitHub.

git clone https://github.com/morphik-org/morphik-core.git

After cloning the repository, you will notice a morphik-core folder in your current directory.

ls morphik-core

If you see an error like ls: morphik-core: No such file or directory, it means that the repository is not cloned properly. Please try again.

Once you have cloned the repository, navigate into the morphik-core folder.

cd morphik-core

Next, you need to set up a virtual environment called .venv.

Setting Up the Environment

Installing Python Dependencies

Morphik currently supports Python 3.12 as the latest version. We recommend using Python 3.12 for optimal compatibility.

python3.12 -m venv .venv

Now, you need to activate the virtual environment. The activation command differs based on your operating system.

source .venv/bin/activate

source .venv/bin/activate

.venv\Scripts\activate.bat

.venv\Scripts\Activate.ps1

If you encounter execution policy errors in PowerShell, you may need to run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

pip install -r requirements.txt

Python Dependencies for Document Processing

You may also need additional Python packages or NLTK resources for processing various document types:

# If using Python 3.12+, you might need a specific version of unstructured
pip install unstructured==0.16.10

# Download required NLTK resources
python -m nltk.downloader averaged_perceptron_tagger punkt

Setting up the Server Parameters

At this point, you may want to customize the server - such as use a different model, enable or disable certain features, etc. - you can do so by editing the morphik.toml file.

Morphik uses environment variables to manage secrets and API keys. In order to ensure that any pre-set keys are available to the server, copy the .env.example file to .env:

cp .env.example .env

python quick_setup.py

Launching the Server

You are now ready to launch the Morphik server! Just run the following command to start the server.

python start_server.py

You should see the following output:

INFO:     Started server process [15169]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://localhost:8000 (Press CTRL+C to quit)

This means that the server is running on http://localhost:8000. You can now interact with the server using the API or the Python SDK.

Using Docker

Morphik provides a streamlined Docker-based setup that includes all necessary components: the core API, PostgreSQL with pgvector, and Ollama for AI models.

Prerequisites

Docker and Docker Compose installed on your system
At least 10GB of free disk space (for models and data)
8GB+ RAM recommended

Quick Start

Clone the repository and navigate to the project directory:

git clone https://github.com/morphik-org/morphik-core.git
cd morphik-core

Before first-time setup, check the configuration:

Ensure your morphik.toml file has the correct settings for running in Docker:

# For Redis configuration when using Docker
[redis]
host = "redis"  # use "redis" when running in Docker (not "localhost")
port = 6379

(If using local models with Ollama) Also ensure the Ollama configuration matches your deployment setup:

If running both Morphik and Ollama as Docker containers:

# If you are running on docker and ollama is also running on docker use the following
ollama_llama_docker_docker = { model_name = "ollama_chat/llama3.2", api_base = "http://ollama:11434" }
ollama_llama_vision_docker_docker = { model_name = "ollama_chat/llama3.2-vision", api_base = "http://ollama:11434", vision = true }

# For embedding models
ollama_embedding_docker_docker = { model_name = "ollama/nomic-embed-text", api_base = "http://ollama:11434" }

If running Morphik in Docker but Ollama locally:

# If you are running on docker, but running ollama locally use the following
ollama_llama_docker = { model_name = "ollama_chat/llama3.2", api_base = "http://host.docker.internal:11434" }
ollama_llama_vision_docker = { model_name = "ollama_chat/llama3.2-vision", api_base = "http://host.docker.internal:11434", vision = true }

# For embedding models
ollama_embedding_docker = { model_name = "ollama/nomic-embed-text", api_base = "http://host.docker.internal:11434" }

And update the active model references to use the appropriate Docker configurations:

[completion]
model = "ollama_llama_vision_docker_docker"  # If both in Docker

[embedding]
model = "ollama_embedding_docker_docker"  # If both in Docker

If you want to use Ollama for AI capabilities (recommended for local development):

docker compose --profile ollama up --build -d

This will build docker with an Ollama container.

Or if you’re using OpenAI, Anthropic, or other models (configure the API key in .env):

docker compose up --build

This will build docker without the Ollama container.

These commands will:

Build all required containers
Download necessary AI models (nomic-embed-text and llama3.2 if using Ollama)
Initialize the PostgreSQL database with pgvector
Start all services

The initial setup may take 5-10 minutes depending on your internet speed, as it needs to download the AI models.

Note: When using Ollama, ensure your system has sufficient memory. The llama3.2 model requires at least 4GB of available RAM. If you encounter memory issues, you can increase Docker’s memory allocation in Docker Desktop settings (Resources > Advanced > Memory), modify the morphik.toml file to use a smaller model, or switch to using OpenAI API.

docker compose up    # Start all services
docker compose down  # Stop all services

To completely reset (will delete all data and models):

docker compose down -v

Configuration

The default configuration works out of the box and includes:

PostgreSQL with pgvector for document storage
Ollama for AI models (embeddings and completions)
Local file storage
Basic authentication

You can customize your setup by creating a .env file:

JWT_SECRET_KEY=your-secure-key-here  # Important: Change in production
OPENAI_API_KEY=sk-...                # Only if using OpenAI
HOST=0.0.0.0                         # Leave as is for Docker
PORT=8000                            # Change if needed

Accessing Services

Morphik API: http://localhost:8000
API Documentation: http://localhost:8000/docs
Health Check: http://localhost:8000/health

Troubleshooting

Service Won’t Start

# View all logs
docker compose logs

# View specific service logs
docker compose logs morphik
docker compose logs postgres
docker compose logs ollama

Database Issues
- Check PostgreSQL is healthy: docker compose ps
- Verify database connection: docker compose exec postgres psql -U morphik -d morphik
Model Download Issues
- Check Ollama logs: docker compose logs ollama
- Ensure enough disk space for models
- Try restarting Ollama: docker compose restart ollama
- Verify that your Redis and Ollama configuration in morphik.toml matches your deployment:
  - For Redis in Docker, use host = "redis" (not “localhost”)
  - If running Ollama in Docker, use http://ollama:11434 endpoint
  - If running Ollama locally but Morphik in Docker, use http://host.docker.internal:11434
Ollama Memory Issues
- If you see errors like “model requires more system memory than is available” in the logs:
  - Increase Docker memory allocation in Docker Desktop:
    1. Open Docker Desktop application
    2. Click on Settings (gear icon)
    3. Go to “Resources” section
    4. Increase memory allocation to at least 6GB (8GB recommended)
    5. Click “Apply & Restart”
  - Alternatively, modify morphik.toml to use a smaller model
  - Or switch to OpenAI API by uncommenting the OpenAI sections in morphik.toml
- For knowledge graph creation specifically, you can switch from Ollama to OpenAI:
  # Change this section in morphik.toml [graph] provider = "openai" model_name = "gpt-4o-mini" enable_entity_resolution = true
Performance Issues
- Monitor resources: docker stats
- Ensure sufficient RAM (8GB+ recommended)
- Check disk space: df -h

Community Support

We have an open community with lots of discussion where you can get help, report bugs, and share your experiences with Morphik. If you need assistance or want to contribute, please join our community!

Join our Discord

Get help, report bugs, and connect with other Morphik users.

Next Steps

Now that you have the server running, you can explore the different ways to interact with the server.

Configure Morphik

Configure Morphik using the morphik.toml file.

API

Use the API to interact with the server.

Python SDK

Use the Python SDK to interact with the server.

Morphik UI and CLI

Use the Morphik UI or CLI to interact with the server.

Get Started

Concepts

Using Morphik

Morphik Community

Getting Started

Installation Options

Direct Installation

Prerequisites

Cloning the Repository

Setting Up the Environment

Installing Python Dependencies

Python Dependencies for Document Processing

Setting up the Server Parameters

Launching the Server

Direct Installation

Prerequisites

Cloning the Repository

Setting Up the Environment

Installing Python Dependencies

Python Dependencies for Document Processing

Setting up the Server Parameters

Launching the Server

Using Docker

Prerequisites

Quick Start

Configuration

Accessing Services

Troubleshooting

Community Support

Join our Discord

Next Steps

Configure Morphik

API

Python SDK

Morphik UI and CLI

Get Started

Concepts

Using Morphik

Morphik Community

​Installation Options

​Direct Installation

​Prerequisites

​Cloning the Repository

​Setting Up the Environment

​Installing Python Dependencies

​Python Dependencies for Document Processing

​Setting up the Server Parameters

​Launching the Server

​Direct Installation

​Prerequisites

​Cloning the Repository

​Setting Up the Environment

​Installing Python Dependencies

​Python Dependencies for Document Processing

​Setting up the Server Parameters

​Launching the Server

​Using Docker

​Prerequisites

​Quick Start

​Configuration

​Accessing Services

​Troubleshooting

​Community Support

Join our Discord

​Next Steps

Configure Morphik

API

Python SDK

Morphik UI and CLI

Installation Options

Direct Installation

Prerequisites

Cloning the Repository

Setting Up the Environment

Installing Python Dependencies

Python Dependencies for Document Processing

Setting up the Server Parameters

Launching the Server

Direct Installation

Prerequisites

Cloning the Repository

Setting Up the Environment

Installing Python Dependencies

Python Dependencies for Document Processing

Setting up the Server Parameters

Launching the Server

Using Docker

Prerequisites

Quick Start

Configuration

Accessing Services

Troubleshooting

Community Support

Next Steps