Installation

Qdrant can be deployed in multiple ways depending on your use case, from local development to production cloud deployments. This guide covers all installation methods.

For production environments, always enable authentication and TLS encryption. See the security guide for best practices.

System Requirements

Before installing Qdrant, ensure your system meets these minimum requirements:

Hardware Requirements

CPU: Modern x86-64 or ARM64 processor (SIMD support recommended)
RAM: Minimum 2GB (depends on collection size and configuration)
Disk: SSD recommended for optimal performance (Qdrant uses async I/O)
Network: Low-latency connection for distributed deployments

Software Requirements

OS: Linux (recommended), macOS, or Windows with WSL2
Docker: Version 20.10+ (for container deployments)
Kubernetes: Version 1.21+ (for K8s deployments)
Rust: Version 1.92+ (for building from source)

Qdrant uses jemalloc for memory allocation on x86-64 and ARM64 architectures, providing better performance than the system allocator.

Docker Installation

Docker is the quickest and most popular way to run Qdrant.

Basic Docker Setup

Pull the latest image

docker pull qdrant/qdrant

Run with default settings

docker run -p 6333:6333 qdrant/qdrant

This starts an insecure deployment without authentication. Never use this configuration in production!

Access the service

Qdrant is now available at:

REST API: http://localhost:6333
Web UI: http://localhost:6333/dashboard

Production Docker Setup

For production use, mount volumes for data persistence and provide custom configuration:

docker run -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/qdrant_storage:/qdrant/storage:z \
    -v $(pwd)/qdrant_snapshots:/qdrant/snapshots:z \
    -v $(pwd)/config/production.yaml:/qdrant/config/production.yaml:z \
    qdrant/qdrant

Understanding the configuration

Ports:

6333: REST API and Web UI
6334: gRPC API (optional, for better performance)

Volumes:

/qdrant/storage: All vector data and indexes (must persist!)
/qdrant/snapshots: Collection backups and snapshots
/qdrant/config/production.yaml: Custom configuration file

Security: The :z suffix on volumes enables SELinux labeling on RHEL/CentOS systems.

Production Configuration Example

Create config/production.yaml with at minimum:

service:
  # Required: Enable API key authentication
  api_key: your_secret_api_key_here
  
  # Optional: Enable TLS
  enable_tls: true
  
  host: 0.0.0.0
  http_port: 6333
  grpc_port: 6334

storage:
  # Persist data to disk
  storage_path: ./storage
  snapshots_path: ./snapshots
  
  # Reduce RAM usage by storing payloads on disk
  on_disk_payload: true
  
  # WAL configuration
  wal:
    wal_capacity_mb: 32
    wal_segments_ahead: 0

Always use TLS when enabling API key authentication. Sending API keys over unencrypted channels is insecure.

Advanced Docker Options

Running as Non-Root User

For enhanced security, run Qdrant with a specific user ID:

docker run -p 6333:6333 \
    -v $(pwd)/qdrant_storage:/qdrant/storage:z \
    -e USER_ID=1000 \
    qdrant/qdrant

GPU Support

Qdrant supports NVIDIA and AMD GPUs for accelerated vector operations:

# Pull GPU-enabled image
docker pull qdrant/qdrant:latest-gpu-nvidia

# Run with GPU access
docker run -p 6333:6333 \
    --gpus all \
    qdrant/qdrant:latest-gpu-nvidia

Docker Compose

For more complex deployments with multiple services, use Docker Compose.

Single Node Deployment

Create docker-compose.yml:

version: '3.8'

services:
  qdrant:
    image: qdrant/qdrant:latest
    container_name: qdrant
    restart: unless-stopped
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - ./qdrant_storage:/qdrant/storage:z
      - ./qdrant_snapshots:/qdrant/snapshots:z
      - ./config/production.yaml:/qdrant/config/production.yaml:z
    environment:
      - QDRANT__SERVICE__GRPC_PORT=6334
    # Optional: healthcheck
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6333/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Start the service:

docker-compose up -d

Distributed Cluster Deployment

For a 3-node cluster with Docker Compose:

version: '3.8'

services:
  qdrant-node-1:
    image: qdrant/qdrant:latest
    container_name: qdrant-node-1
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - ./qdrant_storage_1:/qdrant/storage:z
      - ./qdrant_snapshots_1:/qdrant/snapshots:z
    environment:
      - QDRANT__CLUSTER__ENABLED=true
      - QDRANT__CLUSTER__P2P__PORT=6335

  qdrant-node-2:
    image: qdrant/qdrant:latest
    container_name: qdrant-node-2
    ports:
      - "6433:6333"
      - "6434:6334"
    volumes:
      - ./qdrant_storage_2:/qdrant/storage:z
      - ./qdrant_snapshots_2:/qdrant/snapshots:z
    environment:
      - QDRANT__CLUSTER__ENABLED=true
      - QDRANT__CLUSTER__P2P__PORT=6335
      - QDRANT__CLUSTER__BOOTSTRAP_URI=http://qdrant-node-1:6335
    depends_on:
      - qdrant-node-1

  qdrant-node-3:
    image: qdrant/qdrant:latest
    container_name: qdrant-node-3
    ports:
      - "6533:6333"
      - "6534:6334"
    volumes:
      - ./qdrant_storage_3:/qdrant/storage:z
      - ./qdrant_snapshots_3:/qdrant/snapshots:z
    environment:
      - QDRANT__CLUSTER__ENABLED=true
      - QDRANT__CLUSTER__P2P__PORT=6335
      - QDRANT__CLUSTER__BOOTSTRAP_URI=http://qdrant-node-1:6335
    depends_on:
      - qdrant-node-1

Cluster mode enables horizontal scaling with automatic sharding and replication. The bootstrap_uri points to an existing cluster node.

Kubernetes Deployment

Qdrant provides an official Helm chart for Kubernetes deployments.

Prerequisites

Kubernetes cluster (1.21+)
Helm 3.x installed
kubectl configured

Install with Helm

Add Qdrant Helm repository

helm repo add qdrant https://qdrant.github.io/qdrant-helm
helm repo update

Create a values file

Create qdrant-values.yaml:

replicaCount: 3

image:
  repository: qdrant/qdrant
  tag: latest

service:
  type: LoadBalancer
  port: 6333
  grpcPort: 6334

persistence:
  enabled: true
  size: 10Gi
  storageClass: "standard"

config:
  cluster:
    enabled: true

resources:
  requests:
    memory: "2Gi"
    cpu: "1000m"
  limits:
    memory: "4Gi"
    cpu: "2000m"

# Enable security
apiKey: "your-secret-api-key"

Install Qdrant

helm install qdrant qdrant/qdrant -f qdrant-values.yaml

Verify deployment

kubectl get pods
kubectl get svc qdrant

The Helm chart automatically configures cluster mode, persistent volumes, and health checks for production readiness.

Access Qdrant in Kubernetes

# Port forward for local access
kubectl port-forward svc/qdrant 6333:6333

# Or get the LoadBalancer IP
kubectl get svc qdrant

Build from Source

For development or custom builds, compile Qdrant from source.

Prerequisites

Rust: Version 1.92 or higher
Cargo: Rust’s package manager
Build tools: clang, cmake, protobuf-compiler

sudo apt-get update
sudo apt-get install -y build-essential clang cmake protobuf-compiler libssl-dev pkg-config

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Clone and Build

Clone the repository

git clone https://github.com/qdrant/qdrant.git
cd qdrant

Build in release mode

cargo build --release

This will take several minutes. The binary will be at target/release/qdrant.

Run Qdrant

./target/release/qdrant

Qdrant will start with default settings, reading config from ./config/config.yaml.

Build with Custom Features

# Build with GPU support
cargo build --release --features=gpu

# Build with tracing/profiling support
cargo build --release --features=tracing

# Build with stacktrace support (Linux only)
cargo build --release --features=stacktrace

Available build features

gpu: Enable NVIDIA/AMD GPU acceleration
tracing: Enable distributed tracing support
console: Enable Tokio console for async debugging
stacktrace: Enable stack trace collection (Linux only)
service_debug: Enable parking_lot deadlock detection

Custom Build Options

The Dockerfile shows advanced build options:

# Custom target CPU (for optimization)
export RUSTFLAGS="-C target-cpu=native"

# Use mold linker for faster builds
export RUSTFLAGS="-C link-arg=-fuse-ld=mold"

# Build with specific profile
cargo build --profile perf

Qdrant Cloud

The fastest way to run Qdrant in production without managing infrastructure.

Features

Fully Managed

Zero ops burden - automatic updates, backups, and scaling

High Availability

Built-in redundancy and automatic failover

Global Deployment

Deploy in multiple regions worldwide

Free Tier

Start free with 1GB storage and 1M vectors

Getting Started

Visit cloud.qdrant.io and create an account.

Create a cluster

Choose your region, size, and configuration through the web console.

Get credentials

Copy your cluster URL and API key from the dashboard.

Connect

from qdrant_client import QdrantClient

client = QdrantClient(
    url="https://your-cluster.qdrant.io",
    api_key="your-api-key",
)

Qdrant Cloud automatically handles TLS, authentication, backups, and monitoring - letting you focus on building applications.

Configuration Reference

Qdrant uses YAML configuration files located in the config/ directory.

Key Configuration Sections

Service Configuration

service:
  max_request_size_mb: 32
  max_workers: 0  # 0 = number of CPU cores
  host: 0.0.0.0
  http_port: 6333
  grpc_port: 6334
  enable_cors: true
  enable_tls: false
  
  # Security (required for production)
  api_key: your_secret_api_key_here
  # read_only_api_key: your_read_only_key_here
  # jwt_rbac: true

Storage Configuration

storage:
  storage_path: ./storage
  snapshots_path: ./snapshots
  on_disk_payload: true
  
  # WAL settings
  wal:
    wal_capacity_mb: 32
    wal_segments_ahead: 0
  
  # Performance tuning
  performance:
    max_search_threads: 0
    optimizer_cpu_budget: 0
    update_rate_limit: null

HNSW Index Configuration

hnsw_index:
  m: 16                      # Edges per node
  ef_construct: 100          # Build-time accuracy
  full_scan_threshold_kb: 10000
  max_indexing_threads: 0
  on_disk: false

Cluster Configuration

cluster:
  enabled: false  # Set to true for distributed mode
  
  p2p:
    port: 6335
    enable_tls: false
  
  consensus:
    tick_period_ms: 100
    compact_wal_entries: 128

View the complete reference configuration at config/config.yaml in the source repository.

Environment Variables

You can override any configuration value using environment variables:

# Format: QDRANT__SECTION__SUBSECTION__KEY=value
export QDRANT__SERVICE__API_KEY="secret-key"
export QDRANT__SERVICE__HTTP_PORT=6333
export QDRANT__CLUSTER__ENABLED=true
export QDRANT__STORAGE__STORAGE_PATH="./data"

This is particularly useful in containerized environments.

Ports and Networking

Default Ports

6333: HTTP REST API and Web UI
6334: gRPC API (optional, better performance)
6335: P2P communication (cluster mode only)

Firewall Configuration

Production firewall rules

Public-facing:

Allow inbound TCP 6333 (REST API)
Allow inbound TCP 6334 (gRPC, optional)

Cluster communication (private network only):

Allow TCP 6335 between cluster nodes

Outbound:

Allow HTTPS (443) for license validation and telemetry (optional)

Security Best Practices

Never run Qdrant in production without proper security!

Enable authentication

Set service.api_key in your configuration file.

Enable TLS encryption

service:
  enable_tls: true

tls:
  cert: ./tls/cert.pem
  key: ./tls/key.pem
  ca_cert: ./tls/cacert.pem
  cert_ttl: 3600

Run as non-root user

Use Docker’s USER_ID build arg or Kubernetes security contexts.

Enable read-only mode

Docker: --read-only flag
Kubernetes: readOnlyRootFilesystem: true

Network isolation

Use private networks for cluster communication. Only expose REST/gRPC ports.

Monitoring and Health Checks

Health Check Endpoint

curl http://localhost:6333/healthz

Returns 200 OK when Qdrant is healthy.

Metrics Endpoint

curl http://localhost:6333/metrics

Returns Prometheus-compatible metrics.

Docker Health Check

docker run -p 6333:6333 \
    --health-cmd="curl -f http://localhost:6333/healthz || exit 1" \
    --health-interval=30s \
    --health-timeout=10s \
    --health-retries=3 \
    qdrant/qdrant

Troubleshooting

Common Issues

Port already in use

# Check what's using the port
sudo lsof -i :6333

# Use a different port
docker run -p 7333:6333 qdrant/qdrant

Permission denied on volumes

# Fix permissions on mounted directories
sudo chown -R $(id -u):$(id -g) ./qdrant_storage

# Or use :z flag for SELinux
docker run -v ./qdrant_storage:/qdrant/storage:z qdrant/qdrant

Out of memory errors

Increase RAM or enable memory optimization:

storage:
  on_disk_payload: true  # Store payloads on disk
  
collection:
  vectors:
    on_disk: true  # Store vectors on disk
  
  quantization:
    scalar:
      type: int8  # Use quantization to reduce memory

Logging

View logs with Docker:

docker logs qdrant

# Follow logs
docker logs -f qdrant

# Last 100 lines
docker logs --tail 100 qdrant

Next Steps

Quick Start

Get started with your first collection and search

Configuration Guide

Deep dive into all configuration options

Security Guide

Production security hardening

Performance Tuning

Optimize for your specific use case

Getting Started

Core Concepts

Working with Data

Advanced Features

Deployment

Operations

​Installation

​System Requirements

​Hardware Requirements

​Software Requirements

​Docker Installation

​Basic Docker Setup

​Production Docker Setup

​Production Configuration Example

​Advanced Docker Options

​Running as Non-Root User

​GPU Support

​Docker Compose

​Single Node Deployment

​Distributed Cluster Deployment

​Kubernetes Deployment

​Prerequisites

​Install with Helm

​Access Qdrant in Kubernetes

​Build from Source

​Prerequisites

​Clone and Build

​Build with Custom Features

​Custom Build Options

​Qdrant Cloud

​Features

Fully Managed

High Availability

Global Deployment

Free Tier

​Getting Started

​Configuration Reference

​Key Configuration Sections

​Service Configuration

​Storage Configuration

​HNSW Index Configuration

​Cluster Configuration

​Environment Variables

​Ports and Networking

​Default Ports

​Firewall Configuration

​Security Best Practices

​Monitoring and Health Checks

​Health Check Endpoint

​Metrics Endpoint

​Docker Health Check

​Troubleshooting

​Common Issues

​Logging

​Next Steps

Quick Start

Configuration Guide

Security Guide

Performance Tuning

Installation

System Requirements

Hardware Requirements

Software Requirements

Docker Installation

Basic Docker Setup

Production Docker Setup

Production Configuration Example

Advanced Docker Options

Running as Non-Root User

GPU Support

Docker Compose

Single Node Deployment

Distributed Cluster Deployment

Kubernetes Deployment

Prerequisites

Install with Helm

Access Qdrant in Kubernetes

Build from Source

Prerequisites

Clone and Build

Build with Custom Features

Custom Build Options

Qdrant Cloud

Features

Getting Started

Configuration Reference

Key Configuration Sections

Service Configuration

Storage Configuration

HNSW Index Configuration

Cluster Configuration

Environment Variables

Ports and Networking

Default Ports

Firewall Configuration

Security Best Practices

Monitoring and Health Checks

Health Check Endpoint

Metrics Endpoint

Docker Health Check

Troubleshooting

Common Issues

Logging

Next Steps