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 / aarch64.

Time

~5 minutes

Language

Python 3.11+

Version

v 1.0.62

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 or aarch64 (arm64), glibc 2.28+ (e.g., Debian 10+, Ubuntu 18.10+, Fedora 29+, CentOS/RHEL 8+)

Install Python and pip

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

Install CocoIndex Plus

CocoIndex Plus is published to a private Python index hosted at Keygen, and only there: a cocoindex-plus package on any other index, PyPI included, isn’t CocoIndex Plus. 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

Pass the index with --index-url, never --extra-index-url. The index redirects requests for packages it doesn’t host, such as CocoIndex Plus’s dependencies, to PyPI, so pip needs no second index. Given two, pip treats them as equals and installs the highest version on either, and if the index rejects your token, pip warns and carries on with PyPI alone; the same goes for PIP_EXTRA_INDEX_URL, and for extra-index-url in pip.conf or a requirements file. PyPI’s cocoindex-plus is a placeholder we hold, so today that fallback stops with an error pointing back to this page. With --index-url, pip never asks PyPI for cocoindex-plus at all.

Every pip command that installs cocoindex-plus needs the index. To set it once for a shell or CI job, export PIP_INDEX_URL instead of passing the flag:

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

Using uv

Add this to your pyproject.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

Keep both tables. The [tool.uv.sources] entry makes keygen the only index uv asks for cocoindex-plus. Because the index is explicit, uv asks it for nothing else, so without that entry uv would look cocoindex-plus up on PyPI. The project commands (uv add, uv lock, uv sync, uv run) and uv pip install -e . apply the pin. uv pip install cocoindex-plus and pip don’t — pip install -e . on this project, too, looks cocoindex-plus up on PyPI — so give those the index as for pip.

Using another installer

Pin cocoindex-plus to the index the way the uv tables do, rather than adding the index next to PyPI. In Poetry, add the index as a source (priority = "explicit" keeps your other packages off it) and name it as the source of the cocoindex-plus dependency. Without that, Poetry takes the highest version across its primary sources, and asks a supplemental source only when the others have no match. In PDM, list cocoindex-plus in the source’s include_packages.

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>"

The cocoindex CLI loads .env and --env-file files only after cocoindex is imported, so it can’t supply the key from one.

CocoIndex Plus validates the license key during engine initialization (triggered at import cocoindex). There are two kinds of license, and which one you have is decided when we issue it — not by the key’s format (keys of both kinds can look alike) or by anything you configure. Both use the same COCOINDEX_PLUS_LICENSE_KEY variable:

• Standard license (the default). Unless you asked us for an offline-entitled license, this is the kind you have. It’s validated online against Keygen — once a day per machine by default, at the first start after the previous validation is 24 hours old — so the machine needs outbound HTTPS access to api.keygen.sh.
• Offline-entitled license. For deployments that can’t reach api.keygen.sh at all. It’s verified entirely on the machine, against a public key embedded in CocoIndex Plus, so no network request is ever made.

With a standard license, each successful online validation is cached on the machine’s local disk, and the cache serves two purposes:

• Between validations. A start within 24 hours of the cached validation uses it and sends no request. COCOINDEX_PLUS_LICENSE_REVALIDATE_AFTER, a number of seconds, changes that interval: 0 validates online at every start, and a value above one week is treated as one week. The trade-off is how quickly a license we suspend, revoke, or let expire stops working on a machine that already validated it: at most the interval.
• During an outage. A start that is due to validate but can’t reach Keygen — which can take a few seconds to detect — falls back to the cached validation, provided it’s no more than 1 week old.

Only a successful online validation refreshes the cache, so the day and the week both count from the last successful validation (not from when an outage began), and a freshly created container starts without one. The cache is not an offline mode: past a week, or without a cache, import cocoindex fails until Keygen is reachable again.

If the machine reaches the internet through a proxy, set HTTPS_PROXY. A TLS-inspecting proxy must exempt api.keygen.sh: CocoIndex Plus checks the connection against built-in public CA roots, not your operating system’s trust store. For exactly what the validation request carries, and everything else CocoIndex Plus sends over the network, see Security & data flow.

Offline / air-gapped validation

If your deployment can’t reach api.keygen.sh (for example, it’s air-gapped), ask us for an offline-entitled license. Set its key exactly as issued. Surrounding whitespace is ignored, but anything else — for example, quotes that docker run --env-file keeps as part of the value — stops it from verifying locally.

Offline-entitled licenses have a short term, and the expiry embedded in the key can’t be extended. When yours nears expiration, we’ll renew it by issuing a new key — swap the environment variable and you’re done. Once the expiry passes, import cocoindex fails until you do.

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:

1. Install Docker Compose.

2. Start a Postgres instance configured for CocoIndex:

   Copysh

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

Install the agent skill (optional)

If you use an AI coding agent such as Claude Code, Codex, or Cursor, the official CocoIndex skill teaches it the CocoIndex v1 API. Run this in your project root:

npx skills add https://plus.cocoindex.io/docs

The skill is shared with the open-source edition, so its dependency examples name cocoindex. In a CocoIndex Plus project, depend on cocoindex-plus from the Plus index instead, as in Install CocoIndex Plus. To update the skill or install it for every project, see AI coding agents.

All set

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