Skip to content

Getting Started

What is envd?

envd (ɪnˈvdɪ) is a command-line tool that helps you create the container-based development environment for AI/ML.

Development environments are full of python and system dependencies, CUDA, BASH scripts, Dockerfiles, SSH configurations, Kubernetes YAMLs, and many other clunky things that are always breaking. envd is to solve the problem:

  1. Declare the list of dependencies (CUDA, python packages, your favorite IDE, and so on) in build.envd
  2. Simply run envd up.
  3. Develop in the isolated environment.

Why use envd?

Environments built with envd provide the following features out-of-the-box:

❤️ Knowledge reuse in your team

envd build functions can be reused. Use include function to import any git repositories. No more copy/paste Dockerfile instructions, let's reuse them.

envdlib = include("")

def build():
    base(os="ubuntu20.04", language="python")
envdlib.tensorboard is defined in
def tensorboard(envd_port=6006, envd_dir="/home/envd/logs",
        host_port=0, host_dir="/var/log/tensorboard"):
    """Configure TensorBoard.

    Make sure you have permission for `host_dir`

        envd_port (Optional[int]): port used by envd container
        envd_dir (Optional[str]): log storage mount path in the envd container
        host_port (Optional[int]): port used by the host, if not specified or equals to 0,
            envd will randomly choose a free port
        host_dir (Optional[str]): log storage mount path in the host
    runtime.mount(host_path=host_dir, envd_path=envd_dir)
    runtime.expose(envd_port=envd_port, host_port=host_port, service="tensorboard")

⏱️ BuiltKit native, build up to 6x faster

BuildKit supports parallel builds and software cache (e.g. pip index cache and apt cache). You can enjoy the benefits without knowledge of it.

For example, the PyPI cache is shared across builds and thus the package will be cached if it has been downloaded before.

Setup your first envd environment in 3 minutes


  • Docker (20.10.0 or above)

Install and bootstrap envd

# envd can be installed with pip.
pip3 install --upgrade envd
# If you are on MacOS, envd can be installed with homebrew.
brew install envd
# envd can be installed with pipx.
pipx install envd
# Run the following command in your terminal to install the latest release of envd.
curl -sSfL | sudo bash

After the installation, please run envd bootstrap to bootstrap:

envd bootstrap


You can add --dockerhub-mirror or -m flag when running envd bootstrap, to configure the mirror for registry:

envd bootstrap --dockerhub-mirror

Create an envd environment

Please clone the envd-quick-start:

git clone

The build manifest build.envd looks like:

def build():
    config.repo(url="", description="envd quick start example")
    base(os="ubuntu20.04", language="python3")
    # Configure pip index if needed.
    # config.pip_index(url = "")
    install.python_packages(name = [

Note that we use Python here as an example but please check out examples for other languages such as R and Julia here.

Then please run the command below to set up a new environment:

cd envd-quick-start && envd up
$ cd envd-quick-start && envd up
[+] ⌚ parse build.envd and download/cache dependencies 2.8s ✅ (finished)
 => download oh-my-zsh                                                    2.8s
[+] 🐋 build envd environment 18.3s (25/25) ✅ (finished)
 => create apt source dir                                                 0.0s
 => local://cache-dir                                                     0.1s
 => => transferring cache-dir: 5.12MB                                     0.1s
 => pip install numpy                                                    13.0s
 => copy /oh-my-zsh /home/envd/.oh-my-zsh                                 0.1s
 => mkfile /home/envd/                                          0.0s
 => install oh-my-zsh                                                     0.1s
 => mkfile /home/envd/.zshrc                                              0.0s
 => install shell                                                         0.0s
 => install PyPI packages                                                 0.0s
 => merging all components into one                                       0.3s
 => => merging                                                            0.3s
 => mkfile /home/envd/.gitconfig                                          0.0s
 => exporting to oci image format                                         2.4s
 => => exporting layers                                                   2.0s
 => => exporting manifest sha256:7dbe9494d2a7a39af16d514b997a5a8f08b637f  0.0s
 => => exporting config sha256:1da06b907d53cf8a7312c138c3221e590dedc2717  0.0s
 => => sending tarball                                                    0.4s
envd-quick-start via Py v3.9.13 via 🅒 envd
 [envd]❯ # You are in the container-based environment!

Set up Jupyter notebook

Please edit the build.envd to enable jupyter notebook:

def build():
    config.repo(url="", description="envd quick start example")
    base(os="ubuntu20.04", language="python3")
    # Configure pip index if needed.
    # config.pip_index(url = "")
    install.python_packages(name = [

You can get the endpoint of the running Jupyter notebook via envd envs ls.

$ envd up --detach
$ envd envs ls
NAME                    JUPYTER                 SSH TARGET              CONTEXT                                 IMAGE                   GPU     CUDA    CUDNN   STATUS          CONTAINER ID
envd-quick-start        http://localhost:42779   envd-quick-start.envd   /home/gaocegege/code/envd-quick-start   envd-quick-start:dev    false   <none>  <none>  Up 54 seconds   bd3f6a729e94

Roadmap 🗂️

Please check out ROADMAP.

Contribute 😊

We welcome all kinds of contributions from the open-source community, individuals, and partners.

Develop with gitpod: Open in Gitpod

Talk with us

💬 Interested in talking with us about your experience building or managing AI/ML applications?

Set up a time to chat!

Released under the Apache-2.0 License. Built with VitePress.