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.
You can define a public Docker image in your
.gitpod.yml file with the following configuration:
The official Gitpod Docker images are hosted on Docker Hub.
You can find the source code for these images in this GitHub repository.
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)
This is currently in Alpha.
You may also use private Docker images.
To do so you must provide the registry authentication details to Gitpod by setting
GITPOD_IMAGE_AUTH with the following value
<registry-domain>:<base64-encoded 'username:password'> as a Project-level environment variable.
For example, if the registry is
docker.io, the username is
foo and the password is
GITPOD_IMAGE_AUTH environment variable value may be calculated using the command
echo -n "docker.io:"; echo -n "foo:bar" | base64 -w0 which outputs
This option provides you with the most flexibility. Start by adding the following configuration in your
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
# 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: >
COPYinstructions in a Dockerfile is only evaluated once and then cached. See this to break the cache and trigger a rebuild.
⚠️ Caveat: The base image of a custom Dockerfile must be public.
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
You can however use
sudo in your Dockerfile. The following example shows a typical
.gitpod.Dockerfile inheriting from
# 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.
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 though for a public base image to work properly as a workspace. See the below Dockerfile as a reference. For instance, you’ll need to set up the
gitpod user with the right UID, and install
git to enable your configured dotfiles for the workspace.
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
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
Tailscale: see the Tailscale integration docs for setting up Tailscale in a custom Dockerfile.
.gitpod.Dockerfile is a regular Dockerfile, you can build the image in your Gitpod workspace. This helps you catch syntax or build errors before you commit your changes.
To test your custom
.gitpod.Dockerfile, run the following commands from the project root:
docker build -f .gitpod.Dockerfile -t gitpod-dockerfile-test .
docker run -it gitpod-dockerfile-test bash
This builds a
gitpod-dockerfile-test image and starts a new container based on that image. At this point, you are connected to the Docker container that will be available as the foundation for your Gitpod workspace. You can inspect the container and make sure the necessary tools & libraries are installed.
To exit the container and return back to your Gitpod workspace, type
Once you validated the
.gitpod.Dockerfile with the approach described in the previous chapter, it is time to start a new Gitpod workspace based on that custom image.
The easiest way to try out your changes is as follows:
- Create a new branch.
- Commit your changes & push the branch to your git hosting server.
- Open a pull / merge request and open it in your browser.
- Prefix the URL with
gitpod.io/#and hit Enter.
This starts a new workspace with your changes applied. You notice you now have two Gitpod workspaces running. The one where you made the changes and the new one, based on the pull request.
Caution: Keeping the first workspace open is important in case your Dockerfile has bugs and prevents Gitpod from starting a workspace based on your pull request.
In the second workspace, the Docker build will start and show the output. If your Dockerfile has issues and the build fails or the resulting workspace does not look like you expected, you can force push changes to your config using your first, still running workspace and simply start a fresh workspace again to try them out.
We are working on allowing Docker builds directly from within workspaces, but until then this approach has been proven to be the most productive.
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:
Feedback needed: Custom shell support is in the works. The below shows a method for running some of the
~/.bashrc.dstartup 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:
Tip: You could also create an environment variable at https://gitpod.io/variables called
*/* scope for setting a personal default SHELL.
Caveat: Shells like
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.
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'