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:

1
2
3
4
5

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

Startup

Check the GPUStack container logs:

1

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:

1
2

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

 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:

1
2
3
4
5
6

 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.

1
2
3
4
5

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

Additional Trusted CAs

If GPUStack needs to communicate with services that use certificates issued by a private or corporate CA (e.g., a self-hosted Identity Provider, a Hugging Face mirror, or an internal API endpoint), mount the CA certificate into the container under /usr/local/share/ca-certificates/. GPUStack will automatically import the mounted CA certificates during startup and add them to the system trust store.

1
2
3
4
5
6

 sudo docker run -d --name gpustack \
     ...
     --volume gpustack-data:/var/lib/gpustack \
+    --volume /path/to/custom-root-ca.crt:/usr/local/share/ca-certificates/custom-root-ca.crt:ro \
     gpustack/gpustack
     ...

Installation via Docker Compose

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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:

1

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:

1

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

For built-in and external observability options, see Observability.