Home → Articles → How to Install Qdrant Vector Database on Ubuntu 26.04

How to Install Qdrant Vector Database on Ubuntu 26.04

Published: Last updated:

Introduction

Qdrant is an open-source vector database written in Rust that specializes in high-performance similarity search and vector management. The database stores vectors along with their associated payloads, which are JSON objects containing metadata that filters search results based on specific criteria. Qdrant supports multiple distance metrics including cosine similarity, Euclidean distance, and dot product, making it suitable for recommendation systems, image recognition pipelines, anomaly detection, and semantic text search applications. The database achieves millisecond response times on billion-scale datasets through optimized HNSW (Hierarchical Navigable Small World) indexing and supports both gRPC and REST APIs for client communication.

This guide teaches you how to install Qdrant on Ubuntu 26.04 using Docker containerization.

Prerequisites

Before you start:

  • Deploy an Ubuntu 26.04 server with at least 4GB of RAM and 2 CPU cores.
  • SSH to your server using PuTTY for Windows or Open SSH for Linux and Mac OS.
  • Create a non-root user with sudo privileges.

Install Docker Engine

Qdrant runs inside Docker containers, which provide isolation and consistent behavior across different environments. Docker simplifies the installation process by packaging Qdrant with all its dependencies.

  • Refresh your system's package list to ensure you get the latest available versions.

    console
    $ sudo apt update

  • Install prerequisite packages for Docker.

    console
    $ sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

  • Add Docker's official GPG key.

    console
    $ sudo mkdir -p /etc/apt/keyrings
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

  • Add the Docker repository to your apt sources.

    console
    $ echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

  • Update the package index and install Docker Engine.

    console
    $ sudo apt update
$ sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

  • Add your non-root user to the docker group.

    console
    $ sudo usermod -aG docker $USER

  • Log out and log back in for the group changes to take effect.

    console
    $ exit

After logging back in, verify Docker is working.

console
$ docker --version

Output:

Docker version 28.0.1, build 1234567

Pull the Qdrant Docker Image

Qdrant publishes official Docker images to Docker Hub under the qdrant/qdrant repository. The image includes the complete Qdrant server with web-based UI and API endpoints.

  • Pull the Qdrant Docker image from the official registry.

    console
    $ docker pull qdrant/qdrant:latest

    Output:

    latest: Pulling from qdrant/qdrant
a1234567890b: Pull complete
b2345678901c: Pull complete
c3456789012d: Pull complete
Digest: sha256:def456abc789...
Status: Downloaded newer image for qdrant/qdrant:latest
docker.io/qdrant/qdrant:latest

  • Verify the image downloaded successfully.

    console
    $ docker images | grep qdrant

    Output:

    qdrant/qdrant   latest   def456abc789   1 week ago   1.2GB

Create Qdrant Data Directory

Persistent storage ensures your vector collections and payload data survive container restarts. Create a dedicated directory on your host system for Qdrant to store its data.

  • Create the directory structure for Qdrant.

    console
    $ mkdir -p ~/qdrant/storage
$ mkdir -p ~/qdrant/snapshots

  • Set appropriate permissions for these directories.

    console
    $ chmod -R 755 ~/qdrant

Run Qdrant Container

With the image pulled and directories ready, you can now start the Qdrant container. The docker run command creates a container from the Qdrant image and maps the necessary ports for client connections and web UI access.

  • Start the Qdrant container with persistent storage.

    console
    $ docker run -d \
  --name qdrant \
  --restart unless-stopped \
  -p 6333:6333 \
  -p 6334:6334 \
  -v ~/qdrant/storage:/qdrant/storage \
  -v ~/qdrant/snapshots:/qdrant/snapshots \
  qdrant/qdrant:latest

    Output:

    b2c3d4e5f67890g1h2i3j4k5l6m7n8o9p0q1r2s3t4u5v6w7

Manage Qdrant Container

Docker manages the Qdrant container as a running process on your system. You can control the container using standard Docker commands to start, stop, restart, and check its status.

Check Qdrant Container Status

console
$ docker ps | grep qdrant

Output:

b2c3d4e5f678   qdrant/qdrant:latest   "/entrypoint.sh"   1 minute ago   Up 1 minute   0.0.0.0:6333-6334->6333-6334/tcp   qdrant

View Qdrant Container Logs

console
$ docker logs qdrant

Output:

[2026-03-12T10:15:30.123Z INFO  actix_server::builder] Starting 8 workers
[2026-03-12T10:15:30.456Z INFO  actix_server::server] Actix runtime found; starting in Actix runtime
[2026-03-12T10:15:30.789Z INFO  qdrant] Qdrant is ready to serve requests
[2026-03-12T10:15:30.890Z INFO  qdrant] HTTP API listening on 0.0.0.0:6333
[2026-03-12T10:15:30.901Z INFO  qdrant] gRPC API listening on 0.0.0.0:6334

Press Ctrl + C.

Stop Qdrant Container

console
$ docker stop qdrant

Start Qdrant Container

console
$ docker start qdrant

Restart Qdrant Container

console
$ docker restart qdrant

Configure Firewall for Qdrant

Qdrant uses two ports for client communication. Port 6333 handles REST API calls and serves the web-based dashboard, while port 6334 handles gRPC protocol connections for higher performance.

  • Allow Qdrant REST API port 6333.

    console
    $ sudo ufw allow 6333/tcp

    Output:

    Rule added
Rule added (v6)

  • Allow Qdrant gRPC port 6334.

    console
    $ sudo ufw allow 6334/tcp

    Output:

    Rule added
Rule added (v6)

  • Verify the firewall rules.

    console
    $ sudo ufw status

    Output:

    Status: active

To                         Action      From
--                         ------      ----
6333/tcp                   ALLOW       Anywhere
6334/tcp                   ALLOW       Anywhere
6333/tcp (v6)              ALLOW       Anywhere (v6)
6334/tcp (v6)              ALLOW       Anywhere (v6)

Access Qdrant Web UI

Qdrant includes a built-in web-based dashboard that lets you browse collections, view points, and monitor cluster health without writing any code.

  • Open your web browser and navigate to http://your_server_ip:6333/dashboard.

The Qdrant dashboard loads and shows an empty state with no collections. You can use the dashboard to create collections, upload vectors, and run similarity searches interactively.

Install Python Client for Testing

Qdrant provides a Python SDK called qdrant-client for interacting with the database programmatically. You will use this client to test your installation by connecting to the Qdrant server and performing basic vector operations.

  • Install Python3 and pip if not already present.

    console
    $ sudo apt install -y python3 python3-pip

  • Install the Qdrant Python SDK.

    console
    $ pip3 install qdrant-client

    Output:

    Collecting qdrant-client
Downloading qdrant_client-1.12.0-py3-none-any.whl
Successfully installed qdrant-client-1.12.0

Test Qdrant Installation

Create a Python script to connect to your Qdrant server and perform basic operations. This test verifies that the server accepts connections, creates collections, inserts vectors with payloads, and executes similarity searches with filters.

  • Create a new test script with Nano.

    console
    $ nano test_qdrant.py

  • Add the following test code to test_qdrant.py.

    Python
    from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct
import random

# Connect to Qdrant server
client = QdrantClient(host="localhost", port=6333)
print("Connected to Qdrant server")

# Create a collection
collection_name = "test_collection"
if client.collection_exists(collection_name):
    client.delete_collection(collection_name)

client.create_collection(
    collection_name=collection_name,
    vectors_config=VectorParams(size=8, distance=Distance.COSINE)
)
print(f"Created collection: {collection_name}")

# Insert sample vectors with payloads
points = []
for i in range(5):
    vector = [random.random() for _ in range(8)]
    payload = {"id": i, "category": "sample", "score": random.randint(1, 100)}
    points.append(PointStruct(id=i, vector=vector, payload=payload))

client.upsert(collection_name=collection_name, points=points)
print(f"Inserted {len(points)} vectors with payloads")

# Retrieve collection information
collection_info = client.get_collection(collection_name=collection_name)
print(f"Collection info: {collection_info}")

# Perform a similarity search
search_vector = [random.random() for _ in range(8)]
search_results = client.search(
    collection_name=collection_name,
    query_vector=search_vector,
    limit=3
)

print("Search results:")
for result in search_results:
    print(f"  ID: {result.id}, Score: {result.score}, Payload: {result.payload}")

# Count points in collection
point_count = client.count(collection_name=collection_name)
print(f"Total points in collection: {point_count.count}")

print("Qdrant test completed successfully!")

  • Save and close the file by pressing Ctrl + X + Y.

  • Run the test script.

    console
    $ python3 test_qdrant.py

    Output:

    Connected to Qdrant server
Created collection: test_collection
Inserted 5 vectors with payloads
Collection info: vectors_count=5, payload_schema={...}, segments_count=1
Search results:
ID: 2, Score: 0.987654, Payload: {'id': 2, 'category': 'sample', 'score': 78}
ID: 0, Score: 0.876543, Payload: {'id': 0, 'category': 'sample', 'score': 42}
ID: 4, Score: 0.765432, Payload: {'id': 4, 'category': 'sample', 'score': 91}
Total points in collection: 5
Qdrant test completed successfully!

View Container Resource Usage

Monitor the resource consumption of your Qdrant container to ensure it has adequate memory and CPU for your workloads.

  • Display Docker container statistics.

    console
    $ docker stats qdrant --no-stream

    Output:

    CONTAINER ID   NAME      CPU %     MEM USAGE / LIMIT     MEM %     NET I/O           BLOCK I/O         PIDS
b2c3d4e5f678   qdrant    5.67%     456MB / 3.889GB      11.73%    2.34MB / 1.23MB   12.3MB / 4.56MB   28

Conclusion

In this guide, you have installed Qdrant vector database on Ubuntu 26.04 using Docker, created persistent storage directories for data and snapshots, configured the firewall to expose REST API and gRPC ports, and tested the installation with the Qdrant Python SDK. You also accessed the built-in web dashboard and learned how to manage the Qdrant container with Docker commands. Now that you have Qdrant running, consider integrating it with embedding models like sentence-transformers for semantic text search, CLIP for image similarity, or use it as the vector backend for retrieval-augmented generation (RAG) pipelines with large language models.

  • Database
  • AI
  • Data Science
  • NoSQL