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.

services:
  mongodb:
    image: mongo:4.4.18

Installation

git clone https://github.com/danny-avila/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 --format "{{.ID}}" --filter "reference=*librechat*" | 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 in docker-compose.override.yml:

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

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