By default, Gitpod uses a standard Docker Image called Workspace-Full as the foundation for workspaces. Workspaces started based on this default image come pre-installed with Docker, Nix, Go, Java, Node.js, C/C++, Python, Ruby, Rust, Clojure as well as tools such as Homebrew, Tailscale, Nginx and several more. If this image does not include the tools you need for your project, you can provide a public Docker image or your own Dockerfile. This provides you with the flexibility to install the tools & libraries required for your project.
Gitpod supports Debian/Ubuntu based Docker images out-of-the-box. Some base images like Alpine do not include libgcc and libstdc++ by default, which breaks Visual Studio Code. See a reference Alpine base image and issue #3356.

​
Configuring a Workspace Image

​
Use a public Docker image

You can define a public Docker image in your .gitpod.yml file with the following configuration: 
image: node:buster
The official Gitpod Docker images are hosted on Docker Hub. You can find the source code for these images in this GitHub repository. Docker image tags For public images, feel free to specify a tag, e.g. image: node:buster if you are interested in a particular version of the Docker image. For Gitpod images, we recommend using timestamped tag for maximum reproducibility, for example image: gitpod/workspace-full:2022-05-08-14-31-53 (taken from the Tags panel on this dockerhub page for example)

​
Use a private Docker image

​
Configuring Credentials

Gitpod supports Docker registries that require authentication. You can provide registry credentials using the GITPOD_IMAGE_AUTH environment variable, which accepts the format <registry-domain>:<base64-encoded 'username:password'>. Credentials for different registries can be appended, separated by commas. This environment variable can be configured on either organization, project or user-level.

​
Generating Credentials

To create the required base64-encoded credentials for GITPOD_IMAGE_AUTH, use this script: 
USERNAME='foo'
PASSWORD='bar'
echo -n "docker.io:"; echo -n "$USERNAME:$PASSWORD" | base64
In this example, the registry is Docker Hub (docker.io), the username foo and the password bar, which results in: docker.io:Z2VybzpiYXI=

​
Registry-Specific Instructions

​
Using private images inside workspaces

By default, GITPOD_IMAGE_AUTH is not mounted into workspaces for security reasons. If you need Docker access within your workspace (e.g., for docker pull/docker push or gp validate workflow), enable dockerd authentication in Repository configuration.

​
Troubleshooting

Common issues:
  • Invalid base64 encoding: Ensure no extra characters or line breaks in the encoded string or when copying
  • Wrong registry hostname: Verify the exact registry domain format for your provider
    • for Docker Hub, use docker.io - or drop it entirely, to make use of the library syntax: e.g. bash:latest or just python
  • Expired credentials: Check if tokens or passwords need renewal
  • Permission issues: Ensure the account has pull access to the private repository

​
Using a custom Dockerfile

This option provides you with the most flexibility. Start by adding the following configuration in your .gitpod.yml file: 
image:
    file: .gitpod.Dockerfile
Next, create a .gitpod.Dockerfile file at the root of your project. The syntax is the regular Dockerfile syntax as documented on docs.docker.com. A good starting point for creating a custom .gitpod.Dockerfile is the gitpod/workspace-full image as it already contains all the tools necessary to work with all languages Gitpod supports. 
# You can find the new timestamped tags here: https://hub.docker.com/r/gitpod/workspace-full/tags
FROM gitpod/workspace-full:2022-05-08-14-31-53

# Install custom tools, runtime, etc.
RUN brew install fzf
Caveat: COPY instructions in a Dockerfile is only evaluated once and then cached.
See this to break the cache and trigger a rebuild.
Docker support: If you use the gitpod/workspace-full image, you get Docker support built-in to your environment. If you want a base image without the default tooling installed then use the gitpod/workspace-base image. 
# You can find the new timestamped tags here: https://hub.docker.com/r/gitpod/workspace-base/tags
FROM gitpod/workspace-base:2022-05-08-14-31-53

# Install custom tools, runtime, etc.
# base image only got `apt` as the package manager
# install-packages is a wrapper for `apt` that helps skip a few commands in the docker env.
RUN sudo install-packages shellcheck tree llvm
When you launch a Gitpod workspace, the local console will use the gitpod user, so all local settings, config file, etc. should apply to /home/gitpod or be run using USER gitpod (we no longer recommend using USER root). You can however use sudo in your Dockerfile. The following example shows a typical .gitpod.Dockerfile inheriting from gitpod/workspace-full: 
# You can find the new timestamped tags here: https://hub.docker.com/r/gitpod/workspace-full/tags
FROM gitpod/workspace-full:2022-05-08-14-31-53

# Install custom tools, runtime, etc.
# install-packages is a wrapper for `apt` that helps skip a few commands in the docker env.
RUN sudo install-packages \
          binwalk \
          clang \
          tmux

# Apply user-specific settings
Once committed and pushed, Gitpod will automatically build this Dockerfile when (or before) new workspaces are created. See also Gero’s blog post running through an example.

​
What is available at build time

Available:
  • Git repository at CWD. Note: additionalRepositories from the multi-repos feature will not be available in this context.
    For example, you can copy your repository inside the image and execute a script: 
    FROM gitpod/workspace-full

# At first copy the repository files to ${TARGET_DIR}
ARG TARGET_DIR="/tmp/work"
COPY --chown gitpod:gitpod . "${TARGET_DIR}"

# Let's suppose there is a bash script in our repository, we can try to execute it
RUN cd "${TARGET_DIR}" && bash ./scripts/compile.sh
Not available:
  • Gitpod environment variables, not available due to security reasons.
    If you want to access Gitpod environment variables when building images using the Docker daemon running in your workspace. Here’s what you could do:
    • Prepare a custom dockerfile (.gitpod.Dockerfile), example contents:
    FROM gitpod/workspace-full

# Lets suppose DOWNLOAD_URL is saved as a Gitpod environment variable that is visible (not hidden to the workspace)
RUN curl -L "${DOWNLOAD_URL}" -o "${HOME}/payload.tar"
    • Build an image using the Docker daemon running in your workspace like so: docker build --build-arg DOWNLOAD_URL -f .gitpod.Dockerfile .
    • Push the image to your dockerhub account and change it’s visibility to private.
    • Use the image from your .gitpod.yml:
    image: docker.io/your_username/image
  • Persistent /workspace directory mount
  • /ide layer
  • Gitpod CLI

​
Custom base image

While it is recommended to extend one of the Gitpod-provided base images for custom Dockerfiles to ensure the image has the required dependencies for a workspace, it is possible to configure a Dockerfile with a public (Debian/Ubuntu-based) image as its base. There are some requirements for a public base image to work properly as a workspace. For example, you’ll need to set up the gitpod user with the right UID, and install git to ensure your workspace can start. See the below Dockerfiles as a reference.

​
Ubuntu

FROM ubuntu:latest

# Install:
# - git (and git-lfs), for git operations (to e.g. push your work).
#   Also required for setting up your configured dotfiles in the workspace.
# - sudo, while not required, is recommended to be installed, since the
#   workspace user (`gitpod`) is non-root and won't be able to install
#   and use `sudo` to install any other tools in a live workspace.
RUN apt-get update && apt-get install -yq \
    git \
    git-lfs \
    sudo \
    && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/*

# Create the gitpod user. UID must be 33333.
RUN useradd -l -u 33333 -G sudo -md /home/gitpod -s /bin/bash -p gitpod gitpod

USER gitpod

​
Alpine

FROM alpine:3.18.2

RUN apk add --no-cache \
        # Needed for Gitpod compatibility:
        git\
        # git-lfs \ # uncomment if needed
        bash \
        sudo  \
        docker \
        iptables\
        # Needed for VSCode compatibility:
        libgcc \
        gcompat \
        libstdc++\

    # Add gitpod user
    && echo '%gitpod ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/gitpod \
    && addgroup -g 33333 gitpod && adduser -u 33333 -G gitpod -h /home/gitpod -s /bin/bash -D gitpod
Additional tools & languages: see https://github.com/gitpod-io/workspace-images/tree/main/chunks for references to configure your workspace image with common tools and languages. For instance, this Dockerfile shows how to install docker and docker-compose. Tailscale: see the Tailscale integration docs for setting up Tailscale in a custom Dockerfile.

​
Validate and apply a workspace image

To validate your workspace image is working execute the gp validate command from within the workspace with your configuration changes. For the configuration change to apply for all new workspaces you must commit and push your configuration to source control. For a full guide, see Configuring Workspaces.

​
Manually rebuild a workspace image

Sometimes you find yourself in situations where you want to manually rebuild a workspace image, for example if packages you rely on released a security fix. You can trigger a workspace image rebuild with the following URL pattern: https://gitpod.io/#imagebuild/<your-repo-url>.

​
Configure a custom shell

Feedback needed: Custom shell support is in the works. The below shows a method for running some of the ~/.bashrc.d startup scripts. To leave feedback on the approach, please see this GitHub issue: #10105.
For example, if you wish to default your workspace-image to zsh, you could do it from your custom dockerfile with the following line: 
ENV SHELL=/usr/bin/zsh
Tip: You could also create an environment variable at https://gitpod.io/variables called SHELL with */* scope for setting a personal default SHELL. Caveat: Shells like fish, zsh and etc. are not POSIX-compliant or bash-compatible, so your Gitpod tasks might error if you use some POSIX or bash specific features in your task scripts.

​
Load bash environment in custom shell

Currently we put some startup scripts for the workspace-images at ~/.bashrc.d, that means if you change your SHELL from bash to something else, they will not auto run. You could run the following command from your SHELL to workaround: 
bash -lic 'true'

​
Define Dynamic Global Environment Variables from Dockerfile

Certain resources or contexts available during a running Gitpod workspace are not present within the Docker build environment. If you need to set environment variables that depend on the running workspace and need to be accessible by the editor (e.g., VS Code, JetBrains IDEs) as well as all terminals, you can use the following strategy. This approach should work on Docker images based on most modern Linux distributions. In your Dockerfile, you can add something like below: 
RUN <<EOR

sudo tee -a /etc/bash.bashrc <<'BASH'

# Set global environment variables
## What you see below are some random examples
export USERNAME="${GITPOD_GIT_USER_EMAIL%%@*}"
export SOMETHING_ELSE="$(git -C $GITPOD_REPO_ROOT remote get-url origin)"

BASH

EOR
Bash reads /etc/bash.bashrc before ~/.bashrc for interactive non-login shells, so this configuration is usually applied system-wide from one of the initialization processes. You can read more about this here.

​
FAQs

​
Why is my custom dockerfile rebuilding everytime even with no change made to it?

This usually happens when you don’t pin the image tag (AKA version) inside your custom dockerfile. In such cases, it could be that there has been long gaps between the time you reuse a workspace or create a new one. We usually release new images every week so if there was more than one week between each start then the image will be rebuild every time. So, for example, if your .gitpod.Dockerfile looks like the following: 
FROM gitpod/workspace-full:latest

# ... more stuff
You could grab a timestamped tag from here for gitpod/workspace-full. And then your .gitpod.Dockerfile could look like: 
FROM gitpod/workspace-full:2023-01-16-03-31-28

# ... more stuff
Note: Please grab a recent tag from the linked page, don’t copy paste the example from here. Also see docker-image-tags for more info.

​
How to run a Desktop app for GUI development inside a Gitpod workspace

If you wish to do GUI application development in Gitpod and getting errors such as:
  • Unable to init server: Could not connect : Connection refused
  • No display server running
  • Xorg missing
  • xdg-open command not found
Then you need to use the gitpod/workspace-full-vnc docker image. See this page for more info.