# Choose the right compatibility for your Discord bot
When you create a Discord bot order, the setup flow now asks you to pick a **compatibility** in addition to a runtime (Node.js, Python, Bun, Deno, Java, or Other). This page explains what that choice does, when it matters, and how to change it on a bot you already have running.

## The two options

**Lightweight** is the default. It uses a small base image (Alpine Linux under the hood) which starts faster, uses less disk, and pulls quickly. It's a good fit for most bots: anything that uses pure-JavaScript libraries, pure-Python libraries, the standard Discord SDKs, simple HTTP clients, and so on.

**Standard (Better Compatibility)** uses a larger base image (Debian-based) that ships with the system tooling some libraries expect. You give up a bit of cold-start time and disk for much broader package support.

If your bot installs cleanly today, leave it on **Lightweight**. If it doesn't, **Standard** is almost always the answer.

## When Lightweight is not enough

Some packages download a precompiled binary on install (the "happy path"), and others compile a binary from C/C++ source as part of `npm install` or `pip install`. The Lightweight base doesn't ship a C/C++ toolchain or the system libraries those packages link against, so any package that has to compile will fail.

These are the most common offenders we see:

- **Node.js / npm**: `canvas`, `sharp`, `bcrypt`, `better-sqlite3`, `node-canvas`, `puppeteer`, voice helpers for `discord.js` (`@discordjs/opus`, `sodium-native`), `node-sass`.
- **Python / pip**: `Pillow`, `cryptography`, `lxml`, `numpy` (occasionally), anything that wraps `libffi`, `libxml2`, `libpng`, or `cairo`.

You'll usually find out the hard way: the install crashes with errors mentioning `node-gyp`, `prebuild-install`, `gcc`, `python: not found`, or `Cannot find module`. The bot then keeps restarting in a loop.

:::tip{title="Quick way to tell"}

Open your bot's `package.json` or `requirements.txt`. If you see any of the packages above, start with **Standard**.

:::

## What you give up with Standard

Not much, in practice:

- The image is around 80–150 MB compressed instead of ~50 MB. You won't notice unless you're rebuilding constantly.
- First-time pull is a few seconds slower on a cold node. Subsequent restarts on the same node are identical.
- A slightly larger surface area for security updates. Both bases are maintained by their upstreams and we keep them current.

For a Discord bot that runs for days or weeks at a time, these costs are invisible. We default to Lightweight only because most bots truly don't need anything more.

## Switching an existing bot to Standard

If you already created a bot and it's failing with build errors, you don't need to cancel and re-order. Open the bot from your dashboard, go to **Configuration**, and change the compatibility there. The change applies on the next restart, which will trigger a fresh dependency install on the new base image.

:::warning{title="Old dependencies may need to be cleared"}

If your bot has been failing to install for a while, the `node_modules/` (or `__pycache__/`, `venv/`, etc.) directory on the server's volume may be in a half-broken state. After switching to Standard, if the install still doesn't go through, delete that directory from the file manager and restart once. The runtime will rebuild it from scratch.

:::

## Frequently asked questions

<details>
  <summary>Can I switch from Standard back to Lightweight?</summary>

Yes, in the same place. There's no migration step. If your dependencies install fine on Lightweight, it'll behave exactly the same as a bot that was on Lightweight from day one.

</details>

<details>
  <summary>Does this change the version of Node / Python / Java my bot runs on?</summary>

No. The major version of your runtime (Node 22, Python 3.13, Java 21, etc.) is the same across both options. What changes is the operating-system base underneath, not the language runtime.

</details>

<details>
  <summary>Is Standard slower?</summary>

Once the container is running, no. The runtimes themselves are identical. The only measurable difference is image pull time on a node that has never run that image before, which is a one-off cost.

</details>

<details>
  <summary>Why default to Lightweight if Standard is more compatible?</summary>

Most Discord bots are small, pure-language projects that have no need for a heavier base. Defaulting everyone to Standard would mean larger images and slower cold starts for a majority of bots that would never benefit from it. We surface the choice so the bots that *do* need it can opt in cleanly.

</details>

<details>
  <summary>What if my bot uses the 'Other' runtime with a custom start.sh?</summary>

The same choice applies. **Lightweight** gives you an Alpine shell, **Standard** gives you a Debian shell. If your script calls `apt-get`, you need Standard; if it calls `apk`, you need Lightweight. Pure POSIX scripts run on either.

</details>