Docker

For most scenarios, Docker Compose is the recommended installation method due to its simplicity, ease of use, and reliability.

Prerequisites

• Git
• Docker

Docker Desktop is recommended for most users. For remote server installations, see the Ubuntu Docker Deployment Guide.

System Requirements

LibreChat does not run AI models itself; it sends requests to the providers you configure, so it does not need a GPU.

LibreChat's containers need at least 1 GiB of RAM and 1 vCPU, the same minimum as on a server. The default Docker Compose file starts MongoDB, Meilisearch (conversation search), and the RAG API with a PostgreSQL/pgvector database (file search) alongside LibreChat. It also defines the admin panel, which only starts once ADMIN_PANEL_SESSION_SECRET is set in .env (see Admin Panel). With everything running, make at least 2 GB of memory available to Docker for smoother operation.

If you use Docker Desktop, it runs containers inside its own virtual machine, so your computer also has to meet Docker Desktop's requirements. At the time of writing, those are at least 4 GB of system RAM on macOS and Linux, and 8 GB on Windows, plus hardware virtualization. Check the linked pages for the current requirements. The memory available to containers is set in Docker Desktop's resource settings on macOS, Linux, and Windows with Hyper-V; with the Windows WSL 2 backend, it is set on the WSL 2 virtual machine instead (see Docker's WSL guidance). Docker Engine installed directly on Linux runs containers on the host and has no separate virtual machine.

If you connect LibreChat to models running on the same machine, such as Ollama, size the hardware for the model you choose. That model runtime needs far more memory, and often a GPU, than LibreChat does.

services:
  mongodb:
    image: mongo:4.4.18

Installation

git clone https://github.com/LibreChat-AI/LibreChat.git
cd LibreChat

cp .env.example .env

docker compose up -d

Mounting librechat.yaml

To use a custom librechat.yaml configuration file with Docker, you need to mount it as a volume so the container can access it.

Copy the example override file and edit it:

cp docker-compose.override.yml.example docker-compose.override.yml

Ensure the librechat.yaml volume mount is uncommented in docker-compose.override.yml:

services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml

Restart for changes to take effect:

docker compose down && docker compose up -d

For full setup instructions including creating the file from scratch, see the librechat.yaml guide. For more override options, see the Docker override guide.

Updating LibreChat

The following commands will fetch the latest LibreChat project changes, including any necessary changes to the docker compose files, as well as the latest prebuilt images.

docker compose down

# Linux/Mac
docker images -a | grep "librechat" | awk '{print $3}' | xargs docker rmi

# Windows (PowerShell)
docker images -a --filter "reference=registry.librechat.ai/librechat-ai/librechat*" --format "{{.ID}}" | ForEach-Object { docker rmi $_ }
docker images -a --filter "reference=ghcr.io/librechat-ai/librechat*" --format "{{.ID}}" | ForEach-Object { docker rmi $_ }

git pull

docker compose pull

docker compose up

Troubleshooting

Port Already in Use

If you see an error like bind: address already in use for port 3080, another application is using that port.

Either stop the conflicting application, or change the port LibreChat uses. The default docker-compose.yml publishes "${PORT}:${PORT}", and ports added in an override file are appended to that list instead of replacing it, so an override alone does not free port 3080.

The simplest fix is to set PORT in your .env file, which changes both the port LibreChat listens on and the published port:

PORT=3081

Alternatively, with Docker Compose 2.24.4 or later, replace the published port in docker-compose.override.yml with the !override tag (the container keeps listening on 3080):

services:
  api:
    ports: !override
      - "3081:3080"

Restart with docker compose down && docker compose up -d, then visit http://localhost:3081 instead.

Container Crashes on Startup

If containers exit immediately after starting, check the logs:

docker compose logs api

Common causes:

• Invalid librechat.yaml syntax: validate with the YAML Validator
• Missing .env file -- ensure .env exists in the project root
• Docker not running -- ensure Docker Desktop is open and running

Missing Environment Variables

If features are not working as expected, check that required environment variables are set in your .env file.

docker compose exec api env | grep -i "your_variable"

See the .env reference for all available variables and their defaults.

Next Steps