Skip to main content

Installation

🖥️ System Requirements​

CocoIndex is supported on the following operating systems:

  • macOS: 11.0+ on arm64
  • Linux: x86_64, glibc 2.28+ (e.g., Debian 10+, Ubuntu 18.10+, Fedora 29+, CentOS/RHEL 8+)

🐍 Install Python and Pip​

To follow the steps in this guide, you'll need:

  1. Install Python. We support Python 3.11 to 3.13.
  2. Install pip - a Python package installer

🌴 Install CocoIndex Plus​

Install the enterprise edition from our private Python package index using your activation token. Do not hardcode or share this token.

The exact private index URL is provided alongside your install token. The general form is:

https://token:${COCOINDEX_PLUS_INSTALL_TOKEN}@pypi.pkg.keygen.sh/cocoindex-io/simple

Use pip​

We recommend exporting the token to an environment variable before installing to avoid leaking it via shell history:

export COCOINDEX_PLUS_INSTALL_TOKEN="<your-install-token>"
pip install -U \
  --index-url "https://token:${COCOINDEX_PLUS_INSTALL_TOKEN}@pypi.pkg.keygen.sh/cocoindex-io/simple" \
  cocoindex-plus

Use uv​

Add these to your pyproject.toml file:

[tool.uv.sources]
cocoindex-plus = { index = "keygen" }

[[tool.uv.index]]
name = "keygen"
explicit = true

url = "https://pypi.pkg.keygen.sh/cocoindex-io/simple"

You need to set the following environment variables to use the Keygen index:

export UV_INDEX_KEYGEN_USERNAME=token
export UV_INDEX_KEYGEN_PASSWORD=<your-installation-token>

🔐 Set your CocoIndex Plus license key​

Before running CocoIndex Plus, set the COCOINDEX_PLUS_LICENSE_KEY environment variable. This key is separate from the installation token. CocoIndex Plus validates the license key during startup. Internet access is required for license validation, but the result is securely cached and remains valid for 1 week. This means you only need connectivity for the initial validation or once per week. CocoIndex Plus will continue to work if you are offline in between.

export COCOINDEX_PLUS_LICENSE_KEY="<your-license-key>"
Security Notes
  • DO NOT commit the install token or license key to source control.
  • Tokens and license keys are delivered in separate communications. Store them securely.

📦 Install Postgres​

You can skip this step if you already have a Postgres database with pgvector extension installed.

If you don't have a Postgres database:

  1. Install Docker Compose 🐳.
  2. Start a Postgres SQL database for cocoindex using our docker compose config:
docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex/refs/heads/main/dev/postgres.yaml) up -d

🤖 Install Claude Code Skill (Optional)​

If you're using Claude Code, you can install the CocoIndex skill for enhanced development support. Run these commands in Claude Code:

/plugin marketplace add cocoindex-io/cocoindex-claude
/plugin install cocoindex-skills@cocoindex

This provides specialized CocoIndex knowledge and workflow support within Claude Code.

🎉 All set​

You can now start using CocoIndex.