# Docker (https://www.librechat.ai/docs/local/docker)

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

<Callout type="warn" title="Apple Silicon (M-series) Macs">

Mac computers with Apple Silicon (M1, M2, M3, M4) processors do not support AVX instructions, which are required by the default MongoDB image used in LibreChat's Docker Compose setup. If you're on an M-series Mac, MongoDB will crash on startup.

**Fix:** Create a `docker-compose.override.yml` to use an older, compatible MongoDB image:

```yaml filename="docker-compose.override.yml"
services:
  mongodb:
    image: mongo:4.4.18
```

See the [Docker Override guide](/docs/configuration/docker_override) for more details.

</Callout>

## 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 in Single-Tenant Deployments">

In an unscoped single-tenant deployment, the first account you register becomes the admin account. There are no default credentials -- you create your own username and password during registration. Tenant-scoped deployments do not auto-promote the first user in each tenant; provision tenant administrators through a trusted administrative flow.

</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 --filter "reference=registry.librechat.ai/danny-avila/librechat*" --format "{{.ID}}" | ForEach-Object { docker rmi $_ }
docker images -a --filter "reference=ghcr.io/danny-avila/librechat*" --format "{{.ID}}" | 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>