Installation

Prerequisites

GPUStack server:

• Docker must be installed. Docker Desktop (Windows and macOS) is also supported.

GPUStack workers:

• Docker must be installed. Docker Desktop is not supported.
• Only Linux is supported for GPUStack worker nodes. If you use Windows, consider using WSL2 and avoid using Docker Desktop. macOS is not supported for GPUStack worker nodes.
• Ensure the appropriate GPU drivers and container toolkits are installed for your hardware. See the Installation Requirements for details.

Install GPUStack Server

Run the following command to install and start the GPUStack server using Docker. Port 80 is the primary server endpoint, while port 10161 is used to expose metrics for observability.

sudo docker run -d --name gpustack \
    --restart unless-stopped \
    -p 80:80 \
    -p 10161:10161 \
    --volume gpustack-data:/var/lib/gpustack \
    gpustack/gpustack

Note

GPUStack v2 uses a single unified container image for all GPU device types.

Startup

Check the GPUStack container logs:

sudo docker logs -f gpustack

If everything is normal, open http://your_host_ip in a browser to access the GPUStack UI.

Log in with username admin and the default password. Retrieve the initial password with:

sudo docker exec -it gpustack \
    cat /var/lib/gpustack/initial_admin_password

Add GPU Clusters and Worker Nodes

Please follow the UI instructions on the Clusters and Workers pages to add GPU clusters and worker nodes.

Custom Configuration

The following sections describe examples of custom configuration options when starting the GPUStack server container. For a full list of available options, refer to the CLI Reference.

Enable HTTPS with Custom Certificate

 sudo docker run -d --name gpustack \
     ...
     -p 80:80 \
+    -p 443:443 \
     --volume gpustack-data:/var/lib/gpustack \
+    --volume /path/to/cert_files:/path/to/cert_files:ro \
+    -e GPUSTACK_SSL_KEYFILE=/path/to/cert_files/your_domain.key \
+    -e GPUSTACK_SSL_CERTFILE=/path/to/cert_files/your_domain.crt \
     gpustack/gpustack
     ...

Using an External Database

By default, GPUStack uses an embedded PostgreSQL database. To use an external database such as PostgreSQL or MySQL, set the GPUSTACK_DATABASE_URL environment variable or use the --database-url argument when starting the GPUStack container:

 sudo docker run -d --name gpustack \
     ...
     --volume gpustack-data:/var/lib/gpustack \
+    -e GPUSTACK_DATABASE_URL="postgresql://username:password@host:port/dbname" \
     gpustack/gpustack
     ...

Configure External Server URL

If you use a cloud provider to provision workers, set the external server URL for worker registration to ensure that workers can connect to the server correctly.

sudo docker run -d --name gpustack \
    ...
+   -e GPUSTACK_SERVER_EXTERNAL_URL="https://your_external_server_url" \
    gpustack/gpustack
    ...

Installation via Docker Compose

This guide explains how to deploy GPUStack and observability components (Prometheus, Grafana) using Docker Compose.

Overview of Services

Services:

• gpustack-server: Central server for scheduling, management, and built-in inference.
• prometheus: Metrics collection.
• grafana: Metrics visualization.

Prerequisites

• Docker Compose must be installed.
• Required ports must be available.

Deployment

The Docker Compose files and configuration files are maintained in the GPUStack repository

Run the following commands to clone the latest stable release:

LATEST_TAG=$(
    curl -s "https://api.github.com/repos/gpustack/gpustack/releases" \
    | grep '"tag_name"' \
    | sed -E 's/.*"tag_name": "([^"]+)".*/\1/' \
    | grep -Ev 'rc|beta|alpha|preview' \
    | head -1
)
echo "Latest stable release: $LATEST_TAG"
git clone -b "$LATEST_TAG" https://github.com/gpustack/gpustack.git
cd gpustack/docker-compose

Start the GPUStack server and observability components:

sudo docker compose -f docker-compose.server.yaml up -d

If everything is normal, open http://your_host_ip in a browser to access the GPUStack UI.

Log in with username admin and the default password. Retrieve the initial password with:

sudo docker exec -it gpustack-server cat /var/lib/gpustack/initial_admin_password