Short answer: an HNSW build is fast only while the whole graph fits in maintenance_work_mem. Raise it for the build session to more than the expected index size. If you want parallel workers, check that PostgreSQL will actually start them: for vectors stored in TOAST it often will not, until you set the table's parallel_workers option. In Docker or Kubernetes, give /dev/shm at least as much space as maintenance_work_mem, or the parallel build fails.

HNSW is the index type most teams pick for pgvector, and its build is the slow part. I built the same index 14 times on pgvector 0.8.7 and PostgreSQL 18.6 in Docker, changing memory, workers and shared memory, to see which settings matter. The scripts and full output are in the lab folder.

The test setup

  • pgvector/pgvector:0.8.7-pg18 image: PostgreSQL 18.6, pgvector 0.8.7, on a laptop with 10 CPU cores and 8 GB of memory available to Docker.
  • One table, items(id bigint, embedding vector(768)), 100,000 rows of random values. 768 dimensions is a common size for sentence-embedding models.
  • Index: CREATE INDEX … USING hnsw (embedding vector_cosine_ops) with the defaults m = 16 and ef_construction = 64. The finished index was 391 MB.

Random vectors are a harder case for graph construction than real embeddings, which cluster. Your absolute times will differ. The ratios between settings are what carry over.

maintenance_work_mem: the 5x setting

At the default maintenance_work_mem of 64MB, pgvector stopped building in memory after about 18,000 of the 100,000 rows:

NOTICE:  hnsw graph no longer fits into maintenance_work_mem after 17697 tuples
DETAIL:  Building will take significantly more time.
HINT:  Increase maintenance_work_mem to speed up builds.

From that point it inserts the remaining rows into the on-disk index one at a time, which is much slower than building in memory. Serial build times:

maintenance_work_memBuild timeGraph in memory?
64MB (default)9 min 4 s; 11 min 49 s in a run that requested 2 workers, which did not startOnly the first 17,697 rows
1GB1 min 33 s to 2 min 2 s across 9 runsYes

That is a 5x difference from one setting, and it grows with the table: the in-memory part stays the same size while the slow part grows. Set it for the session that runs the build, not globally:

SET maintenance_work_mem = '1GB';   -- more than the expected index size
CREATE INDEX CONCURRENTLY items_embedding_hnsw
  ON items USING hnsw (embedding vector_cosine_ops);
RESET maintenance_work_mem;

To size it, estimate the index from a build on a sample, or use the existing index size if you are rebuilding. The graph needs roughly the finished index size. Do not set it so high that the build pushes the rest of the server into swap or the out-of-memory killer. On RDS or Aurora, check the instance class memory and what the instance already uses, and remember that a parallel build also allocates that amount as shared memory, below.

Why parallel workers did not start

pgvector supports parallel HNSW builds, and max_parallel_maintenance_workers defaults to 2. In the first round of tests, though, 2, 4 and 8 workers made no difference: 1 minute 46 seconds to 2 minutes 1 second, the same as serial. Sampling pg_stat_activity during the builds showed why:

=== shm=4g maintenance_work_mem=1GB workers=4
sample 1: workers=0 cpu=102.19%
sample 2: workers=0 cpu=99.71%
sample 3: workers=0 cpu=100.08%

No workers, one core busy. PostgreSQL decides how many workers an index build gets from the size of the table's heap, using min_parallel_table_scan_size (8MB by default) as the threshold. The vector type uses EXTERNAL storage, and a 768-dimension vector takes about 3 KB, above the roughly 2 KB at which PostgreSQL moves values out of line. So the vectors live in the TOAST table and the heap holds little more than pointers:

SELECT pg_size_pretty(pg_relation_size('items')) AS heap,
       pg_relation_size('items') / current_setting('block_size')::int AS heap_pages,
       pg_size_pretty(pg_relation_size(reltoastrelid)) AS toast,
       current_setting('min_parallel_table_scan_size') AS min_parallel_table_scan_size
FROM pg_class WHERE oid = 'items'::regclass;

  heap   | heap_pages | toast  | min_parallel_table_scan_size
---------+------------+--------+------------------------------
 5888 kB |        736 | 391 MB | 8MB

A 5.9 MB heap is below the threshold, so the planner assigned zero workers. Raising max_parallel_maintenance_workers changes nothing in that case. The same applies to most embeddings from 512 dimensions up, including 1,536- and 3,072-dimension models. A halfvec(768) column, at about 1.5 KB per value, would usually stay in the heap.

The table storage parameter parallel_workers overrides the size-based calculation. With it set, the workers started:

Workers (parallel_workers and max_parallel_maintenance_workers)Workers seenContainer CPUBuild time
0 (no reloption)0~100%1 min 33 s – 2 min 2 s
22302%53 s
44503%1 min 10 s
88970%1 min 14 s

Two workers halved the build. Four and eight used more CPU and were slower than two: the leader and workers insert into one shared graph and contend for it. Your best number depends on cores, dimensions and data, so time two or three settings on a copy. The procedure that worked:

ALTER TABLE items SET (parallel_workers = 2);
SET maintenance_work_mem = '1GB';
SET max_parallel_maintenance_workers = 2;
CREATE INDEX CONCURRENTLY items_embedding_hnsw
  ON items USING hnsw (embedding vector_cosine_ops);
ALTER TABLE items RESET (parallel_workers);

Reset the option afterwards. parallel_workers also sets the number of workers for parallel queries that scan the table, so leaving it set changes query plans, not just index builds. The workers come from max_parallel_workers and max_worker_processes, both 8 by default; if those are already in use by parallel queries, the build gets fewer workers than it asked for.

The /dev/shm error in Docker and Kubernetes

A parallel build places the graph in dynamic shared memory, sized by maintenance_work_mem. On Linux, PostgreSQL's default dynamic_shared_memory_type is posix, which allocates from /dev/shm. Docker gives a container 64MB there unless told otherwise. With workers running and maintenance_work_mem = 1GB, the build failed at once:

ERROR:  could not resize shared memory segment "/PostgreSQL.323454400" to 1070632480 bytes: No space left on device

1,070,632,480 bytes is just under 1 GiB: the graph's share of the 1GB maintenance_work_mem, requested as one segment. The serial builds never hit this, which is why it surfaces only when someone adds workers, or when a table grows enough for the planner to start them on its own. The fix is to give /dev/shm more room than maintenance_work_mem:

# Docker
docker run --shm-size=2g ... pgvector/pgvector:0.8.7-pg18

# docker compose
services:
  db:
    image: pgvector/pgvector:0.8.7-pg18
    shm_size: 2gb

# Kubernetes: memory-backed volume at /dev/shm (counts toward the pod's memory)
volumes:
  - name: dshm
    emptyDir:
      medium: Memory
      sizeLimit: 2Gi
# container.volumeMounts: - name: dshm, mountPath: /dev/shm

The pgvector README gives the same advice for Docker: keep --shm-size at least as large as maintenance_work_mem. If an operator runs your PostgreSQL pods, check how it sizes /dev/shm before raising maintenance_work_mem on a containerized server. Managed services such as RDS and Aurora handle shared memory themselves.

Watch a build in progress

HNSW builds report through the standard index progress view. pgvector uses two phases, initializing and loading tuples; the view shows the second as building index: loading tuples:

SELECT p.pid, p.phase, p.tuples_done,
       c.reltuples::bigint AS estimated_rows,
       round(100.0 * p.tuples_done / nullif(c.reltuples, 0), 1) AS pct,
       now() - a.query_start AS elapsed
FROM pg_stat_progress_create_index AS p
JOIN pg_stat_activity AS a USING (pid)
JOIN pg_class AS c ON c.oid = p.relid;

In the lab, during the loading phase tuples_total was 0 while the block counters already read 736 of 736, because they count the small heap. tuples_done was the useful counter, so the query above compares it with the planner's row estimate. A build that has printed the "no longer fits" notice slows down after that point, so do not extrapolate the finish time from the first minutes. If a concurrent build is waiting rather than working, see CREATE INDEX CONCURRENTLY stuck?

Build procedure for production

  1. Rehearse on a copy with the real vectors. Record the index size, the build time and whether the notice appears.
  2. Set memory for the session above the rehearsed index size, within what the server can spare.
  3. Check worker planning with the heap and TOAST query. If the heap is smaller than min_parallel_table_scan_size, set parallel_workers for the build and reset it afterwards. In containers, check /dev/shm first.
  4. Build with CONCURRENTLY so writes continue. It takes longer and waits for running transactions; schedule it outside the peak.
  5. Validate: check indisvalid, then measure recall and latency against exact search for representative queries, including filtered ones. A fast build with poor recall is not a result. See HNSW vs IVFFlat and filtered search returning too few rows.

If you are on pgvector 0.8.6 or earlier, upgrade before rebuilding. The 0.8.7 security fix covers IVFFlat builds, and the upgrade is a good moment to schedule the rebuild window.

FAQ

Why is my pgvector HNSW index build so slow?

Usually because the graph does not fit in maintenance_work_mem. pgvector prints "hnsw graph no longer fits into maintenance_work_mem after N tuples" and continues much more slowly. In a test with 100,000 768-dimension vectors, the build took 9 minutes 4 seconds at the 64MB default and between 1 minute 33 seconds and 2 minutes 2 seconds at 1GB.

How much maintenance_work_mem does an HNSW build need?

Enough to hold the whole graph, which is roughly the size of the finished index. In the test, the index was 391 MB and a 1GB setting kept the build in memory. Set it per session for the build, and leave headroom for the rest of the server; parallel builds also allocate that amount as shared memory.

Why does my HNSW build not use parallel workers?

PostgreSQL decides the number of workers from the size of the table heap. Vectors of more than about 500 dimensions are stored out of line in TOAST, so the heap stays small. In the test, the heap was 5.9 MB against 391 MB of TOAST, below the 8MB min_parallel_table_scan_size, so no workers started. Setting the table reloption parallel_workers made them start.

What does "could not resize shared memory segment ... No space left on device" mean during an HNSW build?

The parallel build tried to allocate maintenance_work_mem as a POSIX shared memory segment in /dev/shm, and /dev/shm was too small. Docker gives containers 64MB by default. Start the container with --shm-size at least as large as maintenance_work_mem, or mount a larger memory-backed volume at /dev/shm in Kubernetes.

Do more parallel workers always make HNSW builds faster?

No. In the test, two workers cut the build from about 1 minute 45 seconds to 53 seconds, while four and eight workers took 70 and 74 seconds. Workers insert into one shared graph and contend for it. Measure two or three settings on a copy of your data before picking one.

Sources