repo2docker/docs/source/start.md

Get started

This tutorial guides you through installing repo2docker and building your first environment image.

(install)=

Install repo2docker

repo2docker requires Python 3.6 or above on Linux and macOS.

:::{admonition} Windows support is experimental

This article about using Windows and the WSL (Windows Subsystem for Linux or Bash on Windows) provides additional information about Windows and Docker. :::

Prerequisite: Install Docker

Install Docker, as it is required to build Docker images. The Community Edition is available for free.

Recent versions of Docker are recommended.

Install repo2docker with pip

The name of the package on [PyPI](https://pypi.org/) is [`jupyter-repo2docker`](https://pypi.org/project/jupyter-repo2docker/) instead of `repo2docker`.

We recommend installing repo2docker with the pip tool:

python3 -m pip install jupyter-repo2docker

(usage)=

Build a repository with repo2docker

Now that you've installed Docker and repo2docker, we can build a repository. To do so, follow these steps.

Start Docker

Follow the instructions for starting Docker to start a Docker process.

Build an image from a URL

Next we'll build a reproducible image from a URL. We'll use the Binder requirements.txt example, which installs a simple Python environment. Run the following command:

jupyter-repo2docker https://github.com/binder-examples/requirements

You'll see repo2docker take the following actions:

1. Inspect the repository for configuration files. It will detect the requirements.txt file in the repository.
2. Build a Docker image using the configuration files. In this case, the requirements.txt file will correspond to a Python environment.
3. Run the image to let you explore the repository interactively.

Click the link provided and you'll be taken to an interactive Jupyter Notebook interface where you can run commands interactively inside the environment.

Learn more

This is a simple example building an environment image for your repository. To learn more about the kinds of source repositories, environments, and use-cases that repo2docker supports, see the repo2docker user guide.