For users who need to run Morphik on their own infrastructure, we provide two installation options: Direct Installation and Docker.

​
Direct Installation

1

Prerequisites

Please ensure that you have Python 3.12 installed on your machine. Guides for installing Python can be found on the Python website.
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.
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
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
Docker is used to spin up auxiliary services automatically (e.g., a local Redis container for Morphik’s task queue). Install Docker Desktop (macOS/Windows) or the Docker engine (Linux) and make sure the daemon is running.
Morphik supports fully local inference for both embeddings and completions through two powerful engines:
  • Lemonade SDK - Windows only, optimized for AMD GPUs/NPUs
  • Ollama - Cross-platform (Windows, macOS, Linux)
Both are pre-configured in Morphik. For detailed setup instructions, see our Local Inference Guide.
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, navigate into the morphik-core folder.
cd morphik-core
3

Run the Installer Script

Choose the installer for your OS:
From the project root, run:
# Make the script executable
chmod +x install_and_start.sh

# Run the installer
./install_and_start.sh
The installers will:
  1. Create & activate a .venv with uv
  2. Ask about GPU availability for multimodal embeddings (macOS/Linux)
  3. Install colpali-engine (for multimodal document understanding)
  4. Install or build llama-cpp-python (Metal on Apple Silicon, wheel on Windows)
  5. Launch the server via uv run start_server.py
You only need to run ./install_and_start.sh the first time to set up the environment. For future sessions, activate your project directory and simply start the server with:
uv run start_server.py
4

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 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.The installer copies .env.example to .env automatically if it’s missing. After the script finishes, open .env to add any API keys (e.g. OPENAI_API_KEY) or secrets you need. You can tweak morphik.toml anytime to switch completion/embedding models, adjust chunking, or enable advanced features.
5

Launching the Server

You are now ready to launch the Morphik server! Just run the following command to start the server.
uv run 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.