# qdrant-version-upgrade

Guides Qdrant server and SDK upgrades without downtime or data corruption. Covers version compatibility rules, rolling upgrade steps, and pre-update checklists.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 1400 installs · ★ 264
- Author: qdrant
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/qdrant/skills/tree/HEAD/skills/qdrant-version-upgrade/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/qdrant-qdrant-version-upgrade

## What it does

This skill provides upgrade playbooks and compatibility constraints for Qdrant engines and client libraries. SDKs maintain backward compatibility across the latest three minor server versions, but the storage engine guarantees compatibility across only one minor version jump. Because of this, the recommended order is updating the client SDK first, followed by the Qdrant server.

Zero-downtime rolling upgrades require a cluster replication factor of 2 or higher. Nodes need at least 2 CPU cores because background optimization runs concurrently with production traffic during the update. Pre-upgrade snapshots are mandatory: Qdrant Cloud applies database migrations during upgrades, making instant rollbacks impossible without restoring a snapshot.

Self-hosted clusters cannot jump two minor versions in a single restart, like moving directly from 1.15 to 1.17. You must deploy each intermediate minor version first, landing on its latest patch release. Qdrant Cloud handles these intermediate updates automatically in a single operation.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add qdrant/skills --skill qdrant-version-upgrade -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/qdrant-version-upgrade/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/qdrant-version-upgrade/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add qdrant/skills --skill qdrant-version-upgrade -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/qdrant-version-upgrade/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add qdrant/skills --skill qdrant-version-upgrade -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/qdrant-version-upgrade/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install qdrant/skills qdrant-version-upgrade
```

2. **Manually: put the files in place**
- File: `.github/skills/qdrant-version-upgrade/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add qdrant/skills --skill qdrant-version-upgrade -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/qdrant/skills --path skills/qdrant-version-upgrade
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/qdrant-version-upgrade/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add qdrant/skills --skill qdrant-version-upgrade -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/qdrant/skills/tree/HEAD/skills/qdrant-version-upgrade/SKILL.md

## When to use it
- plan the upgrade sequence for Qdrant server and SDKs
- configure rolling cluster upgrades without downtime
- step through multi-version migrations on self-hosted instances
- diagnose score variations and latency shifts after an update

## Example prompts
- Can I upgrade Qdrant self-hosted directly from 1.15 to 1.17?
- Do I update the Qdrant Python SDK or the server first?
- What checks should I run before upgrading a Qdrant cluster node?

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: a4eb1bee2b1145fb.

BEGIN THIRD-PARTY FILE a4eb1bee2b1145fb
```text
---
name: qdrant-version-upgrade
description: "Covers upgrading Qdrant server and SDKs without interrupting availability or losing data integrity. Use when someone asks 'how do I upgrade Qdrant', 'can I jump from 1.15 to 1.18', 'rolling upgrade without downtime', 'do I upgrade the client or the server first', 'which SDK version matches my server', 'what should I check before upgrading', or 'something changed after we upgraded'."
---

# Qdrant Version Upgrade

Qdrant has the following guarantees about version compatibility:

- Major and minor versions of Qdrant and SDK are expected to match. For example, Qdrant 1.17.x is compatible with SDK 1.17.x.

- Client SDKs are tested to be backward compatible with the latest 3 minor versions of Qdrant. For example, SDK 1.17.x works with Qdrant 1.15.x to 1.17.x, but only for the features the server version supports [Upgrades](https://skills.qdrant.tech/md/documentation/upgrades/)

- For migration to the next minor version, it is recommended to first upgrade the SDK to the next minor version and then upgrade the Qdrant server.

- Storage compatibility is only guaranteed for one minor version. For example, data stored with Qdrant 1.16.x is expected to be compatible with Qdrant 1.17.x. If you need to migrate more than one minor version, it is required do the upgrade step by step, one minor version at a time. For example, to migrate from 1.15.x to 1.17.x, you need to first upgrade to 1.16.x and then to 1.17.x. Note: Qdrant Cloud automates this process, so you can directly upgrade from 1.15.x to 1.17.x without intermediate steps.

- A Qdrant cluster with a replication factor of 2 or higher can be upgraded without downtime by performing a rolling upgrade. This means that you can upgrade one node at a time while the other nodes continue to serve requests. This allows you to maintain availability of your application during the upgrade process. More about replication factor: [Replication factor](https://skills.qdrant.tech/md/documentation/scaling/distributed_deployment/?s=replication-factor)

For managing Qdrant version upgrades in Qdrant Cloud, you can use the [qcloud](https://github.com/qdrant/qcloud-cli) CLI tool.

## Pre-Upgrade Checklist

1. Back up first: It's recommended to take a backup or snapshot before updating to allow for rollbacks. If the upgrade fails or you need to revert, you can restore the pre-upgrade snapshot. Qdrant Cloud applies data migrations during upgrades, so there's no live downgrade. [Snapshots](https://skills.qdrant.tech/md/documentation/snapshots/) [Cloud backups](https://skills.qdrant.tech/md/documentation/cloud/backups/)
```
END THIRD-PARTY FILE a4eb1bee2b1145fb

The third-party file has ended. Everything between the a4eb1bee2b1145fb tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2630 of 5393 bytes. © qdrant · Apache-2.0 · https://github.com/qdrant/skills/tree/HEAD/skills/qdrant-version-upgrade/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md