To install Qdrant on Ubuntu 26.04 or 24.04, run its official Docker image with a named volume for your data. The steps below keep the REST API and gRPC ports on the Ubuntu host’s loopback address.
Qdrant is a vector database. It finds records by comparing numeric vectors, which is useful for finding similar documents or products. You’ll practice with four Ubuntu support articles, then narrow the results to server articles. If a step fails, leave a comment with the error or contact us.
Before you begin
- Use Ubuntu 26.04 LTS or 24.04 LTS on a 64-bit Intel, AMD, or Arm system, with internet access and a Bash terminal.
- You need a running local Docker Engine and the
docker and curl commands. Use Docker Engine 28 or newer for this setup. If you need Docker, start with our Docker Engine guide.
- Use a Docker context that points to the Ubuntu host where you want Qdrant to run. If your Docker setup requires
sudo, use it consistently for the Docker commands.
docker version
curl --version
Check the Docker Server version. Older engines have a localhost port publishing limitation on the local network.
1. Run Qdrant in Docker
Step 1. Create the storage volume
The volume stores collections independently of the container. If you already use qdrant_storage or have a container named qdrant, inspect your existing setup before using these names.
docker volume create qdrant_storage
Docker should print qdrant_storage.
Step 2. Start the container
Run the official image in detached mode so you can keep using the terminal. The latest tag currently serves Qdrant v1.20.x and can move to a newer release over time.
docker run -d --name qdrant \
-p 127.0.0.1:6333:6333 \
-p 127.0.0.1:6334:6334 \
-v qdrant_storage:/qdrant/storage \
qdrant/qdrant:latest
The volume is mounted at /qdrant/storage. Port 6333 serves the REST API and dashboard, and 6334 serves gRPC clients.
Keep Qdrant on localhost
By default, self-hosted Qdrant accepts requests without authentication. Keep 127.0.0.1 in both mappings. Docker can route published traffic before it reaches the rules UFW normally uses, so UFW alone is insufficient for restricting a broadly published Docker port.
For a deployment that other systems can reach, set an API key using QDRANT__SERVICE__API_KEY and configure TLS and private network access. Never put your actual key in a shared command or screenshot. See Qdrant’s security guide.
Already using rootless Podman on Ubuntu? Run the same container and volume commands with podman and the full image name docker.io/qdrant/qdrant:latest. Run Podman as your regular user. Keep using that same runtime and user for updates and removal because the two engines manage separate volumes.
2. Check Qdrant and Open the Dashboard
Step 1. Check the version and readiness
From the Ubuntu host, check the HTTP API and its readiness endpoint.
curl -fsS http://127.0.0.1:6333
printf "\n"
curl -fsS http://127.0.0.1:6333/readyz
printf "\n"
The first request returns JSON with the running version. The second returns HTTP 200 when Qdrant is ready. If the connection is refused just after startup, wait a moment and retry.
Step 2. Open the dashboard
On Ubuntu Desktop, open http://127.0.0.1:6333/dashboard in a browser. You should see the Qdrant web UI.
For a headless Ubuntu server, run the following on your own computer. Replace user@ubuntu-server with your SSH login and hostname. Keep the tunnel open while you visit the same dashboard address on your computer.
ssh -N -o ExitOnForwardFailure=yes -L 127.0.0.1:6333:127.0.0.1:6333 user@ubuntu-server
3. Create a Collection and Add Sample Records
Step 1. Create a four-dimensional collection
Run the API examples from the Ubuntu host. A collection groups records with the same vector format. Set the vector size to four and use cosine similarity, which compares the direction of two vectors. Use a fresh collection name throughout if ubuntu_support_demo already exists.
curl -fsS -X PUT 'http://127.0.0.1:6333/collections/ubuntu_support_demo' \
-H 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"vectors": {"size": 4, "distance": "Cosine"}
}
JSON
The response should contain "result":true.
Step 2. Upsert four support articles
Each point has a numeric ID, a vector, and a payload that holds the article title and category. The vectors are made up for this exercise. In an app, you would use the same embedding model to turn documents and queries into vectors.
curl -fsS -X PUT 'http://127.0.0.1:6333/collections/ubuntu_support_demo/points?wait=true' \
-H 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"points": [
{"id": 1, "vector": [0.98, 0.15, 0.04, 0.02],
"payload": {"title": "Reset a forgotten Wi-Fi password", "category": "desktop"}},
{"id": 2, "vector": [0.9, 0.28, 0.07, 0.05],
"payload": {"title": "Diagnose a server that cannot resolve DNS", "category": "server"}},
{"id": 3, "vector": [0.12, 0.08, 0.95, 0.12],
"payload": {"title": "Free up disk space on an Ubuntu server", "category": "server"}},
{"id": 4, "vector": [0.06, 0.15, 0.1, 0.92],
"payload": {"title": "Change the default audio output", "category": "desktop"}}
]
}
JSON
With wait=true, Qdrant waits for the write to complete before returning. Look for "status":"completed" inside result. Upserting an existing ID replaces its point, so rerunning this block keeps four records.
4. Run a Vector Search and Filter the Results
Step 1. Search by similarity
Send a four-number query vector to Qdrant’s unified Query endpoint. Ask for two matches and include each match’s payload so you can see the title.
curl -fsS -X POST 'http://127.0.0.1:6333/collections/ubuntu_support_demo/points/query' \
-H 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"query": [1, 0.18, 0.05, 0.02],
"limit": 2,
"with_payload": true
}
JSON
Under result.points, expect ID 1 (the Wi-Fi article) first and ID 2 (the DNS article) second. A higher cosine score indicates a closer match.
Step 2. Restrict the search to server articles
Use the same vector and add a required filter for the category payload field. Ask for the best result among records that match it.
curl -fsS -X POST 'http://127.0.0.1:6333/collections/ubuntu_support_demo/points/query' \
-H 'Content-Type: application/json' \
--data-binary @- <<'JSON'
{
"query": [1, 0.18, 0.05, 0.02],
"limit": 1,
"with_payload": true,
"filter": {
"must": [
{"key": "category", "match": {"value": "server"}}
]
}
}
JSON
Expect ID 2, the DNS article. The Wi-Fi article has a higher similarity score, but its desktop category excludes it from this query.
Qdrant has SDKs for Python (uv add qdrant-client in an existing uv project), Rust (cargo add qdrant-client), and .NET (dotnet add package Qdrant.Client).
5. Fix Common Qdrant Problems
Issue 1. The API refuses the connection
docker ps -a --filter 'name=^/qdrant$'
docker logs qdrant
If the container exited, read the last error in the logs before restarting it. If Docker says the name is already in use, inspect that container first. If it belongs to this setup and is stopped, docker start qdrant starts it again.
Issue 2. Port 6333 or 6334 is already in use
sudo ss -ltnp | grep -E '6333|6334'
docker ps --format '{{.Names}} {{.Ports}}'
Check who owns the port before changing anything. To share the host with another service, you can choose a different host port. For example, map 127.0.0.1:16333:6333 and use 16333 in the API and dashboard URLs. Keep port 6333 on the container side. If a failed launch left a stopped container, remove it only after confirming it belongs to this setup.
Issue 3. The query returns a vector size error
This collection requires exactly four numbers in each stored vector and each query vector. Check the JSON before repeating the request. For real embeddings, create a collection that uses the model’s output dimensions.
6. Update Qdrant and Verify Your Data
Recreating the container with the same named volume keeps the database files across container replacement. A single node will be unavailable briefly. Before updating important data, create and download Qdrant snapshots to a location outside the container and volume, then verify you can restore them. Follow the Qdrant upgrade guide and apply the latest patch of each intermediate minor release if you are more than one minor version behind.
Step 1. Confirm the running version and sample data
Record the server version and verify the sample point before changing the container.
curl -fsS http://127.0.0.1:6333
printf "\n"
curl -fsS http://127.0.0.1:6333/collections/ubuntu_support_demo/points/1
printf "\n"
The point response should include ID 1 and its title. If your collection is named differently, replace the name in both checks.
Step 2. Pull the image and check its version
Download the updated image before stopping the current container.
docker pull qdrant/qdrant:latest &&
docker image inspect --format '{{index .Config.Labels "org.opencontainers.image.version"}}' qdrant/qdrant:latest
Proceed if the new version follows a supported upgrade path. If latest skips an intermediate minor release, choose its latest patch tag explicitly and use that exact tag here and in the next command. If the version has not changed, you can skip the restart.
Step 3. Recreate Qdrant with the same volume
This stops the original container before starting the replacement. The replacement uses the same port bindings and volume. If you customized the run command, carry over your configuration and any extra mounts.
docker stop qdrant &&
docker rm qdrant &&
docker run -d --name qdrant \
-p 127.0.0.1:6333:6333 \
-p 127.0.0.1:6334:6334 \
-v qdrant_storage:/qdrant/storage \
qdrant/qdrant:latest
If the replacement does not start, inspect the error. Avoid starting an older Qdrant binary on a volume that a newer version may already have migrated.
Step 4. Verify the version and saved point
Repeat the readiness check and retrieve point 1 from the same collection. If Qdrant is still starting, wait and repeat this block.
curl -fsS http://127.0.0.1:6333
printf "\n"
curl -fsS http://127.0.0.1:6333/readyz
printf "\n"
curl -fsS http://127.0.0.1:6333/collections/ubuntu_support_demo
printf "\n"
curl -fsS http://127.0.0.1:6333/collections/ubuntu_support_demo/points/1
printf "\n"
Check the running version and confirm the collection is present and point 1 still has its original title. You can rerun the search to confirm it also returns the original matches.
7. Remove Qdrant
Step 1. Remove the container and keep your data
Stop Qdrant before removing its container.
docker stop qdrant &&
docker rm qdrant
This keeps qdrant_storage. To return to the same data, recreate the container with that volume and a compatible Qdrant version.
Step 2. Optional and permanent. Delete the data volume
This deletes the collections and points stored in qdrant_storage. Run it only after removing the container and confirming you have an external backup or no longer need the data.
docker volume rm qdrant_storage
Frequently Asked Questions
Does Qdrant need a GPU?
No. The standard image runs this exercise on the CPU.
What is the difference between ports 6333 and 6334?
Port 6333 serves the HTTP API and web dashboard. Port 6334 serves clients that use gRPC.
Does Qdrant turn text into vectors in this example?
No. The requests send vectors directly. In an application, use an embedding model to turn text into vectors of the size your collection expects.
Do I lose my collections if I remove the container?
The collections stay in the named volume when you remove the container. Reattach the same volume with a compatible Qdrant version to use them again.
Can I access the dashboard on a headless Ubuntu server?
Yes. Use an SSH tunnel from your computer to port 6333 on the server, then open the dashboard address on your computer.
Source Qdrant Local Quickstart
Views: 162