CocoIndex Plus installation

Install CocoIndex Plus from the Keygen private index and configure your license key. Python 3.11+ on macOS arm64 or Linux x86_64.

Time: ~5 minutes
Language: Python 3.11+
Version: v 1.0.14
Last reviewed: Jul 4, 2026

CocoIndex Plus is the enterprise edition of CocoIndex. It ships closed-source binaries from a private Python package index and validates a license key at runtime. This guide walks through both pieces.

System requirements

CocoIndex Plus 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

Install Python. We support Python 3.11+.
Install pip, a Python package installer.

Install CocoIndex Plus

CocoIndex Plus is published to a private Python index hosted at Keygen. You need an install token (delivered with your subscription) to fetch it. The general index URL is:

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

Using pip

Export the token to an environment variable rather than hard-coding it in the command — otherwise it ends up in your 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

Using uv

Add this to your pyproject.toml:

toml

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

[[tool.uv.index]]
name = "keygen"
explicit = true
url = "https://pypi.pkg.keygen.sh/cocoindex-io/simple"

Then provide the install token through environment variables:

export UV_INDEX_KEYGEN_USERNAME=token
export UV_INDEX_KEYGEN_PASSWORD="<your-install-token>"
uv add cocoindex-plus

Set your CocoIndex Plus license key

Before running anything that imports cocoindex, set the COCOINDEX_PLUS_LICENSE_KEY environment variable. This is a separate credential from the install token.

export COCOINDEX_PLUS_LICENSE_KEY="<your-license-key>"

CocoIndex Plus validates the license key during engine initialization (triggered at import cocoindex). There are two kinds of license keys, and CocoIndex automatically detects which one you have from its format — both use the same COCOINDEX_PLUS_LICENSE_KEY variable:

Standard key (the default). Validated against Keygen over the network on startup. The signed response is cached locally and stays valid for up to 1 week, so you only need connectivity for the initial validation or once per week — the CLI and library keep working offline in between.
Offline (signed) key. A cryptographically signed key of the form key/<data>.<signature>. It carries its own license data and is verified locally against a public key embedded in CocoIndex Plus, so no network request is ever made. This is the right choice for fully air-gapped environments.

Offline / air-gapped validation

If your deployment has no outbound internet access, ask us for an offline license key. It looks like this and is set exactly the same way:

export COCOINDEX_PLUS_LICENSE_KEY="key/eyJhY2NvdW50Ijp7…fX0=.iJVUYxR…"

An offline key embeds its own expiry, so when it nears expiration we’ll issue a replacement — swap the environment variable and you’re done. No validation traffic leaves your machine at any point.

Note

Standard keys and offline keys are issued from different Keygen policies. If you need to switch modes, contact us for the appropriate key — you don’t need to change any code or configuration beyond the environment variable.

Security notes

Don’t commit the install token or license key to source control.
The install token and license key are delivered in separate communications — store both somewhere your shell can read them (e.g. a secrets manager, .envrc, or your CI’s secret store), not in plaintext in ~/.bashrc.

Install Postgres

Skip this step if you already have a Postgres database with the pgvector extension installed.

If you don’t have Postgres yet, the quickest path is Docker Compose:

Install Docker Compose.

Start a Postgres instance configured for CocoIndex:

docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex/refs/heads/main/dev/postgres.yaml) up -d

Install the Claude Code skill (optional)

If you use Claude Code, the official CocoIndex skill adds workflow guidance directly inside the agent. Run these inside Claude Code:

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

All set

You’re ready to start using CocoIndex Plus. Continue with the quickstart to build your first index.