librechat.ai/content/docs/local/docker.mdx

---
title: Docker
icon: Container
description: How to install LibreChat locally with Docker, verify your setup, and configure custom endpoints
---

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

## Prerequisites

- [`Git`](https://git-scm.com/downloads)
- [`Docker`](https://www.docker.com/products/docker-desktop/)

Docker Desktop is recommended for most users. For remote server installations, see the [Ubuntu Docker Deployment Guide](/docs/remote/docker_linux).

## Installation

<Steps>
  <Step>

### Clone the Repository

```bash
git clone https://github.com/danny-avila/LibreChat.git
cd LibreChat
```

  </Step>
  <Step>

### Create Your Environment File

```bash
cp .env.example .env
```

The default `.env` file works out of the box for a basic setup. For in-depth configuration, see the [.env reference](/docs/configuration/dotenv).

<Callout type="info" title="Windows">

On Windows, use `copy .env.example .env` if `cp` is not available.

</Callout>

  </Step>
  <Step>

### Start LibreChat

```bash
docker compose up -d
```

The first launch pulls Docker images and may take a few minutes. Subsequent starts are much faster.

  </Step>
  <Step>

### Verify and Log In

Open your browser and visit [http://localhost:3080](http://localhost:3080). You should see the LibreChat login page.

<Callout type="info" title="First Account = Admin">

The first account you register becomes the admin account. There are no default credentials -- you create your own username and password during registration.

</Callout>

Click **Register** to create your account and start using LibreChat.

  </Step>
</Steps>

## 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:

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

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

```yaml filename="docker-compose.override.yml"
services:
  api:
    volumes:
      - type: bind
        source: ./librechat.yaml
        target: /app/librechat.yaml
```

Restart for changes to take effect:

```bash
docker compose down && docker compose up -d
```

For full setup instructions including creating the file from scratch, see the [librechat.yaml guide](/docs/configuration/librechat_yaml). For more override options, see the [Docker override guide](/docs/configuration/docker_override).

## 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.

<Callout type="info" title="Permissions">

You may need to prefix commands with `sudo` according to your environment permissions.

</Callout>

```bash filename="Stop the running container(s)"
docker compose down
```

```bash filename="Remove all existing docker images"
# 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 $_ }
```

```bash filename="Pull latest project changes"
git pull
```

```bash filename="Pull the latest LibreChat image"
docker compose pull
```

```bash filename="Start LibreChat"
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`:

```yaml filename="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:

```bash
docker compose logs api
```

Common causes:

- Invalid `librechat.yaml` syntax -- validate with the [YAML Validator](/toolkit/yaml_checker)
- 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.

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

See the [.env reference](/docs/configuration/dotenv) for all available variables and their defaults.

## Next Steps

<Cards num={3}>
  <Cards.Card title="Custom Endpoints" href="/docs/quick_start/custom_endpoints" arrow>
    Add OpenRouter, Ollama, and other AI providers
  </Cards.Card>
  <Cards.Card title="Configuration Overview" href="/docs/configuration" arrow>
    Understand how LibreChat's config files work together
  </Cards.Card>
  <Cards.Card title="Authentication Setup" href="/docs/configuration/authentication" arrow>
    Configure OAuth, LDAP, and other login methods
  </Cards.Card>
</Cards>