Installing and Running WebODM Locally: The Complete Setup Guide

You downloaded 400 drone images from a bridge inspection. The client needs an orthomosaic by Friday. Pix4D’s subscription lapsed, Metashape’s license is on your other machine, and you need to process right now.

WebODM runs on your hardware, costs nothing, and produces survey-grade orthomosaics, point clouds, DSMs, and 3D models using ODX, its own photogrammetry engine (forked from ODM). On Windows and macOS, the easiest route is the free installer. On Linux, you run it in Docker. And if you pick Docker on Windows, Docker has opinions about how much RAM you’re allowed to use.

This guide covers both routes: the free installers for Windows and macOS, and the Docker setup that Linux needs and some Windows and Mac users prefer (Docker install, WebODM clone and launch). Then it walks through your first processing task and every error message I’ve hit along the way. Every command is copy-paste ready.

What WebODM Actually Is

WebODM is free, open-source photogrammetry software that runs in your browser. Since April 2026 it has been a separate project from OpenDroneMap, and it processes imagery with ODX, its own engine, which was forked from OpenDroneMap’s ODM. You upload drone images, configure processing parameters, and get back orthomosaics, digital surface models, point clouds, and textured 3D meshes. Same deliverables as Pix4D or Metashape. No license key. No subscription.

Under the hood, WebODM is a Django web application that dispatches processing jobs to NodeODX, WebODM’s fork of NodeODM: a separate service that runs the ODX engine. In a Docker install, everything runs in containers. When you start WebODM, Docker spins up the web interface, a background worker, a Redis broker, a PostgreSQL database, and the processing node. Five containers, one command.

The current release is WebODM 3.3.2 (October 29, 2026). The Windows installer ships 3.3.2 and the macOS installer 3.3.0. As of 3.3.2, all Windows binaries are signed. The Docker setup uses Docker Compose to orchestrate everything, with separate compose files for GPU acceleration, SSL, and development configurations. If you’re untangling the WebODM, ODX, and OpenDroneMap names, the ecosystem explainer maps every component.

Before You Install: Hardware Reality Check

WebODM will install on almost anything. Processing drone imagery is a different story. The ODX engine is memory-hungry, and its needs grow with image count. The RAM figures below are WebODM’s documented estimates, which it describes as conservative; the processing times are my own rough estimates, not measurements. For one real data point, a forum study on an 8-core Ryzen 7 5700G, CPU only, took about 1.8 hours for 473 12 MP images and 2.5 hours for 1,002, at high feature and medium point cloud quality, on 2022 software. That’s faster than my estimates below, so treat them as cautious.

Official minimum and recommended specs:

• RAM: 8 GB minimum, which handles about 100 images. 16 GB or more is recommended. In practice, budget 32 GB if you’re processing anything beyond test datasets.
• CPU: 64-bit (on Windows, with SSE3/SSSE3 support). More cores speed up processing but increase memory usage. An 8-core machine is the practical sweet spot.
• Disk: 20 GB free minimum, 100 GB recommended. Processing generates intermediate files — budget 6x your input image size in temporary disk space. A 10 GB image set needs 60 GB of scratch space.
• GPU: Optional. ODX supports NVIDIA CUDA GPUs to speed up certain computations. In a Docker install on Linux or WSL, that needs the NVIDIA Container Toolkit and the --gpu flag. On Windows, ODX enables GPU acceleration by default.

To put it plainly: if your machine can’t run Metashape comfortably, it won’t run WebODM comfortably either. The laws of photogrammetry don’t change because the software is free.

Choose Your Install Path

WebODM’s download page lists three routes:

• Windows: a free installer that runs WebODM natively. No Docker, no WSL. Requires Windows 10 or later.
• macOS: a free installer that is, in WebODM’s words, “simply a manager program to help you setup WebODM with docker”. Requires macOS 13 or later; Apple Silicon is supported.
• Linux: Docker, git clone, and ./webodm.sh start. WebODM calls Linux its best supported platform.

Windows and macOS: The Free Installer

Download the installer for your platform from webodm.org/download, run it, and follow the prompts. That’s the whole install. Once WebODM is running, skip ahead to Step 3: First Login and Orientation. Everything from there on (first task, task queue, results) applies to any install method. The Docker-specific commands and errors don’t.

If you bought a WebODM installer in the past, the download page’s FAQ confirms you can install the new free one to update.

Linux, or Docker by Choice

On Linux, Docker is the install path. On Windows and macOS it’s optional, and worth choosing if you want to manage WebODM with the same webodm.sh commands you’d use on a Linux server. Steps 1 and 2 cover the Docker route.

Step 1: Install Docker

In a Docker install, WebODM runs inside Docker containers, so Docker comes first. Here’s what each platform needs.

Windows

Requirements:

• Windows 10 version 22H2 (build 19045) or Windows 11 version 23H2 (build 22631) or later
• 64-bit processor with Second Level Address Translation (SLAT)
• 8 GB system RAM minimum (16 GB recommended for WebODM)
• Hardware virtualization enabled in BIOS (VT-x on Intel, AMD-V on AMD)
• WSL 2 version 2.1.5 or later

Install WSL 2 first:

wsl --install

Restart your machine. WSL 2 installs Ubuntu by default — that’s fine. You need the Linux kernel, not a specific distro.

Install Docker Desktop:

Download from docker.com/products/docker-desktop. Run the installer. Select “Use WSL 2 instead of Hyper-V” when prompted. Restart again.

After restart, open Docker Desktop and verify it’s running. You’ll see the whale icon in your system tray.

Critical step most guides skip — configure resources:

WSL 2 caps its VM, and with it Docker Desktop, at 50% of your system memory by default. For WebODM, that’s not enough.

Create or edit C:\Users\YourUsername\.wslconfig:

[wsl2]
memory=24GB
processors=6
swap=32GB

Adjust memory to leave 4–8 GB for Windows itself. If you have 32 GB total, allocate 24 GB. If you have 64 GB, allocate 56 GB. Set swap to at least your physical memory allocation — this is your safety net when ODX hits peak memory during dense matching.

Restart WSL for changes to take effect:

wsl --shutdown

Then reopen Docker Desktop.

macOS

Requirements:

• A macOS version Docker Desktop currently supports (the current and two previous major releases)
• Apple Silicon (M1/M2/M3/M4) or Intel with VT-x
• 8 GB RAM minimum (16 GB recommended)

Download Docker Desktop from docker.com/products/docker-desktop. Open the .dmg, drag to Applications, launch.

Configure resources:

Docker Desktop > Settings > Resources > Advanced. Set memory to at least 8 GB — 16 GB if your machine has 32 GB or more. CPU cores: at least 4. Disk usage limit: at least 100 GB.

Click “Apply & Restart.”

Linux

Docker runs natively on Linux — no virtualization layer, no WSL, no resource limits to configure. That’s a big part of why Linux is WebODM’s best supported platform.

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y docker.io docker-compose-v2 git
sudo usermod -aG docker $USER

Log out and back in for the group change to take effect.

Verify Docker is running:

docker --version
docker compose version

You should see Docker 24+ and Compose v2+. If docker compose doesn’t work but docker-compose does, you have the legacy Compose — it’ll work, but consider upgrading.

For GPU acceleration on Linux:

# Install NVIDIA Container Toolkit
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Step 2: Clone and Start WebODM

Same process on Linux, and on Windows or Mac if you’re taking the Docker route. Open Git Bash on Windows (or a WSL shell), Terminal on Mac, or your shell on Linux.

git clone https://github.com/WebODM/WebODM --config core.autocrlf=input --depth 1
cd WebODM
./webodm.sh start

The first run pulls Docker images — webodm/webodm_webapp, webodm/webodm_db, webodm/nodeodx, and redis. Expect 2–5 GB of downloads depending on your connection. Subsequent starts take 10–30 seconds.

When you see output like:

Open a web browser and navigate to http://localhost:8000

You’re live.

With GPU acceleration (Linux/WSL only):

./webodm.sh start --gpu

This launches NodeODX from the webodm/nodeodx:gpu image with NVIDIA runtime access. Requires the NVIDIA Container Toolkit (see above).

Step 3: First Login and Orientation

Open your browser and navigate to http://localhost:8000.

You’ll see the WebODM login page. On first launch, it prompts you to create an admin account — pick a username and password. This is local-only, stored in WebODM’s own database. No data leaves your machine.

After login, you land on the Dashboard. Key areas:

• Projects — top-level organizational containers. One per job site or client.
• Tasks — individual processing runs within a project. Each task is one dataset uploaded and processed.
• Processing Nodes — the list of NodeODX instances available. By default, you have one: node-odx-1 (port 3000), running on the same machine as WebODM.

Step 4: Upload Images and Run Your First Task

1. Click “Add Project” — name it something meaningful. “Bridge Inspection - Test” works.
2. Inside the project, click “Select Images and GCP” — drag in your drone images. JPEG or TIFF. WebODM also accepts a GCP file if you have one (gcp_list.txt). Give any checkpoint a CHK- label prefix so it’s reported as a checkpoint rather than used as control.
3. Click “Review” to see processing options.

Processing options that matter:

• dsm: Generate a Digital Surface Model. Default is on.
• dtm: Generate a Digital Terrain Model. Turn this on if you need bare-earth elevation.
• orthophoto-resolution: Output resolution in cm/pixel. Default is 5. Lower numbers mean higher resolution and significantly more processing time and memory.
• feature-quality: ultra, high, medium, low, lowest. Default is high. Start with “medium” on your first run. “Ultra” will consume all your RAM on large datasets.
• pc-quality: Point cloud quality. Same scale. “Medium” is safe for testing.
• min-num-features: Minimum features per image. Default 10000 is fine for most datasets.

4. Click “Start Processing”.

The task enters the queue on your local NodeODX instance. You can monitor progress in the task panel — it shows the current stage (dataset, opensfm, openmvs, odm_filterpoints, etc.) and a progress bar.

Processing a 100-image dataset on a 32 GB machine with 8 cores takes roughly 30–60 minutes at medium quality. My rough estimate for 500 images at the same settings is 3–6 hours. Plan accordingly.

Step 5: Understanding the Task Queue

WebODM processes one task at a time per NodeODX instance. If you submit three tasks, they queue — first in, first out. The second task won’t start until the first finishes or fails.

This is where WebODM’s architecture matters. Each NodeODX instance is an independent processing worker. Want parallel processing? Add more nodes. To manage nodes yourself instead of using the built-in one, start with:

./webodm.sh start --default-nodes 0

Then add nodes manually through the WebODM UI, or run additional NodeODX containers on separate ports. For serious production use, most operators run NodeODX on dedicated processing machines and point WebODM at them over the network.

WebODM also supports ClusterODX — WebODM’s fork of ClusterODM, a load balancer that distributes tasks across multiple NodeODX instances. That’s beyond a local install guide, but worth knowing it exists when your queue grows.

Step 6: Accessing Your Results

Once processing completes, click on the task. You get:

• 2D Map — the orthomosaic displayed on a web map. Pan, zoom, measure. Export as GeoTIFF.
• 3D View — textured mesh or point cloud in the browser. WebODM uses Potree for point cloud visualization.
• Downloads — orthophoto (GeoTIFF), DSM (GeoTIFF), DTM (GeoTIFF), point cloud (LAZ), textured model (OBJ), camera positions, and the quality report.

The quality report is your accuracy paper trail. It covers image overlap, average reprojection error, camera calibration (initial versus optimized), and GCP error statistics. If you tagged checkpoints with CHK-, it adds a separate Checkpoints table listing each one’s X, Y, and Z error.

In a Docker install, output files are stored by default in a Docker named volume (appmedia), organized by task. If you’d rather have them in a regular folder you can browse directly, start WebODM with ./webodm.sh start --media-dir /path/to/folder.

The GeoTIFFs are georeferenced and ready to load into QGIS, ArcGIS, or any GIS platform. The LAZ point cloud opens in CloudCompare, Potree, or any LAS-compatible viewer.

Installer vs. Docker: The Trade-off

Both routes are free. On Linux, Docker is the only route; on Windows and macOS you can choose. Here’s the honest comparison:

The installer is the easy choice on Windows, and it sidesteps WSL memory configuration entirely. On macOS it handles the Docker setup for you. Docker is the right choice if you’re on Linux, or you need fine-grained control over the deployment.

Linux has no native installer. Docker runs natively there with full hardware access, so the friction the installers solve doesn’t exist.

One thing to watch for: OpenDroneMap sells installers for forks of WebODM, called “WebUI” or “OpenDroneMap Desktop”. As WebODM’s own site puts it, those are not WebODM. WebODM itself is downloaded free from webodm.org/download.

WebODM Lightning: The Cloud Alternative

If your machine can’t handle the processing — or you don’t want to wait hours for a 500-image dataset — WebODM Lightning is the hosted alternative at webodm.net.

Lightning is operated by UAV4GEO and processes on LGT, a separate photogrammetry engine that’s only available on Lightning. You can use it from your browser, or add it as a processing node inside your self-hosted WebODM, so processing happens on their hardware.

The trade-off: you’re uploading potentially gigabytes of imagery over the internet, and you’re paying for it. Lightning offers Pay As You Go, or Starter, Pro, and Business plans at $24, $35, and $99 per month billed yearly ($29, $42, and $119 billed monthly). New users get 150 free credits. For operators with limited hardware or occasional processing needs, Lightning makes sense. For daily processing or sensitive data that can’t leave your network, local is the answer.

You can run both — local NodeODX for small jobs and quick turnaround, Lightning for large datasets that would choke your workstation. WebODM lets you switch processing nodes per task.

Common Errors and How to Fix Them

I’ve hit every one of these. Here are the actual error messages and actual fixes. The memory errors can hit any install; the rest are specific to the Docker route.

”Processing node went offline”

What happened: NodeODX ran out of memory and Docker killed the container.

Fix: Reduce feature-quality and pc-quality to “medium” or “low.” If you’re on Windows, check your .wslconfig — the memory limit is probably too low. Increase swap allocation. On Linux, check dmesg | grep -i oom for out-of-memory killer logs.

”Not enough memory” during processing

What happened: ODX’s dense matching stage exceeded available RAM + swap.

Fix on Windows: Edit .wslconfig to allocate more memory and swap, then run wsl --shutdown and restart Docker Desktop. Set swap to at least your memory allocation.

Fix on Linux: Add swap space:

sudo fallocate -l 32G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Add to /etc/fstab to persist across reboots.

Port 8000 already in use

What happened: Another service is using port 8000.

Fix: Either stop the conflicting service or start WebODM on a different port:

./webodm.sh start --port 9000

Then access at http://localhost:9000.

”Cannot connect to the Docker daemon”

What happened: Docker isn’t running.

Fix on Windows/Mac: Open Docker Desktop and wait for it to finish starting. Check the system tray icon.

Fix on Linux:

sudo systemctl start docker
sudo systemctl enable docker

“VT-x/AMD-V not enabled” or “Hardware virtualization not available”

What happened: Your BIOS has virtualization disabled.

Fix: Restart, enter BIOS (usually F2, F12, or DEL during boot), find Intel VT-x or AMD-V under CPU settings, enable it. Save and exit. This is a hard requirement — Docker cannot run without hardware virtualization on Windows.

”No space left on device”

What happened: Docker’s virtual disk, or the drive it lives on, is full.

Fix: Docker Desktop > Settings > Resources > Advanced > Disk usage limit. Increase to at least 100 GB. Apply and restart.

Alternatively, prune unused Docker data:

docker system prune -a

This removes all stopped containers, unused images, and build cache. You’ll re-download WebODM images on next start — budget 2–5 GB.

Managing Your WebODM Installation

If you installed with Docker, these are the commands you’ll use regularly:

# Start WebODM
./webodm.sh start

# Stop WebODM
./webodm.sh stop

# Update to latest version
./webodm.sh update

# Restart with GPU support
./webodm.sh restart --gpu

# Start without default processing node (add your own)
./webodm.sh restart --default-nodes 0

# Enable SSL for network access
./webodm.sh restart --ssl --hostname webodm.mycompany.com

# Check running containers
docker ps

Your project data persists across restarts in Docker volumes — webodm_appmedia and webodm_dbdata. ./webodm.sh down removes the containers but keeps these volumes. Don’t delete webodm_appmedia or webodm_dbdata unless you mean to wipe your projects.

WebODM is professional-grade photogrammetry software that runs on your hardware for free. The installation is a free installer on Windows or macOS, or a Docker pull and a shell script on Linux. The gotchas are mostly resource-related — memory limits on Windows Docker installs, disk space, swap allocation.

If you’re on Linux with 32+ GB of RAM, you’ll be processing within 15 minutes of starting this guide. If you take the Docker route on Windows, budget an extra 30 minutes for WSL and Docker configuration; the installer skips that.

The software is the easy part. The hard part is the same as every other photogrammetry platform: good input data, proper GCPs, and enough patience to let the machine grind through dense matching without killing the process because it looks frozen. It’s not frozen. It’s doing math.

For more on choosing the right processing software for your workflow, check out Pix4D vs Metashape vs WebODM vs RealityScan.