Skip to content

docs: base images support Fedora/RHEL/Arch/Alpine (drop Debian-only restriction) #313

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
tomassrnka wants to merge 3 commits into
base: main
Choose a base branch
from
+26 −4
Draft

docs: base images support Fedora/RHEL/Arch/Alpine (drop Debian-only restriction) #313

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b73ffb9
docs(template): base images now support Fedora/RHEL/Arch/Alpine, not …
tomassrnka Jul 26, 2026
0c6a4ca
docs(template): match Fedora/Alpine examples to the SDK defaults
tomassrnka Jul 30, 2026
2164b84
docs(template): document NixOS base image via e2bdev/nixos
beran-t Jul 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 26 additions & 4 deletions docs/template/base-image.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,19 +31,22 @@ template = Template(

Every template starts with a base image that provides the foundation for your sandbox environment.

<Warning>
E2B currently supports only Debian-based images. Your base image must be Debian or a Debian derivative (e.g., `debian`, `ubuntu`, `python`, `node`). Alpine, RedHat-based, and other non-Debian distributions are not supported.
</Warning>
<Note>
E2B identifies your base image from its `/etc/os-release` and supports **Debian/Ubuntu, Fedora and the RHEL family (including Rocky Linux and AlmaLinux), Arch, and Alpine**. Images with no identifiable distribution — no `/etc/os-release`, e.g. `scratch`, distroless, or pure `nixos/nix` — and minimal images missing required packages (e.g. RHEL UBI-minimal with restricted repositories) are not supported and fail the build with a clear error naming the reason. For NixOS, use the official [`e2bdev/nixos`](#nixos-base-image) image instead of a raw NixOS image.
</Note>

### Predefined base images

Use convenience methods for common base images with Ubuntu, Debian, Python, Node.js, or Bun:
Use convenience methods for common base images with Ubuntu, Debian, Fedora, Alpine, Arch, Python, Node.js, or Bun:

<CodeGroup>

```typescript JavaScript & TypeScript
template.fromUbuntuImage("22.04"); // ubuntu:22.04
template.fromDebianImage("stable-slim"); // debian:stable-slim
template.fromFedoraImage("44"); // fedora:44
template.fromAlpineImage("3.24"); // alpine:3.24
template.fromArchImage("base-devel"); // archlinux:base-devel
Comment thread
tomassrnka marked this conversation as resolved.
template.fromPythonImage("3.13"); // python:3.13
template.fromNodeImage("lts"); // node:lts
template.fromBunImage("1.3"); // oven/bun:1.3
Expand All @@ -52,6 +55,9 @@ template.fromBunImage("1.3"); // oven/bun:1.3
```python Python
template.from_ubuntu_image("22.04") # ubuntu:22.04
template.from_debian_image("stable-slim") # debian:stable-slim
template.from_fedora_image("44") # fedora:44
template.from_alpine_image("3.24") # alpine:3.24
template.from_arch_image("base-devel") # archlinux:base-devel
template.from_python_image("3.13") # python:3.13
template.from_node_image("lts") # node:lts
template.from_bun_image("1.3") # oven/bun:1.3
Expand Down Expand Up @@ -93,6 +99,22 @@ template.from_base_image() # e2bdev/base

`base` is also the template used when you call `Sandbox.create()` without specifying one. It is Debian-based and comes with common tooling pre-installed: Python 3, Node.js, Yarn, `git`, `curl`, `build-essential`, and the GitHub CLI (`gh`). For the exact contents, see the public Dockerfile: [`templates/base/e2b.Dockerfile`](https://github.com/e2b-dev/E2B/blob/main/templates/base/e2b.Dockerfile).

### NixOS base image

Arbitrary [NixOS](https://nixos.org/) images (such as `nixos/nix`) aren't supported directly, because they don't expose the `/etc/os-release` metadata E2B needs to identify the distribution. To build NixOS-based sandboxes, use the official `e2bdev/nixos` image, which E2B prepares to work with the sandbox environment:

<CodeGroup>

```typescript JavaScript & TypeScript
template.fromImage("e2bdev/nixos");
```

```python Python
template.from_image("e2bdev/nixos")
```

</CodeGroup>

### Default resources

A sandbox gets its CPU and memory from the template it's built on. A sandbox built from `base` starts with **2 vCPU and 512 MiB of RAM**.
Expand Down