# How do Binder launch links work or "wait I can do that with a link?"

**URL:** <https://discourse.jupyter.org/t/how-do-binder-launch-links-work-or-wait-i-can-do-that-with-a-link/647>\
**Category:** Binder\
**Created:** [March 30, 2019, 5:07pm UTC](https://discourse.jupyter.org/t/how-do-binder-launch-links-work-or-wait-i-can-do-that-with-a-link/647 "2019-03-30T17:07:07Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![betatim](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/betatim/32/10_2.png) [@betatim](https://discourse.jupyter.org/u/betatim)\
**Post date:** [March 30, 2019, 5:07pm UTC](https://discourse.jupyter.org/t/how-do-binder-launch-links-work-or-wait-i-can-do-that-with-a-link/647/1 "2019-03-30T17:07:07Z")

</div>

This is a post that explain what the different parts of a Binder launch link mean.

What is a Binder launch link? This is one:

[https://mybinder.org/v2/gh/binder-examples/requirements/master](https://mybinder.org/v2/gh/binder-examples/requirements/master)

If you click this link it will take you to a live binder based on the latest commit in [the binder `requirements.txt` example repository](https://github.com/binder-examples/requirements). Why?

### Basic patterns

A Binder link consists of three parts, in the case of the example above they are:

1. `gh`
2. `binder-examples/requirements`, and
3. `master`

The first part determines tells us that this repository is hosted on GitHub. Other options for this part are `gl` ([Gitlab.com](http://Gitlab.com)), `gist` (a GitHub gist) or `git` (any kind of git repository). The format for the the second part of the URL changes depending on which option you choose.

The second part of the URL (`binder-examples/requirements`) tells us which repository on [GitHub.com](http://GitHub.com) we should pick. In this case it is the `requirements` repository in the `binder-examples` organisation. If instead you wanted to launch the `conda` repository from the same organisation this part would be `binder-examples/conda`.

The third part tells us which revision inside the repository we want to use. In this case we specify `master`. This isn’t actually a specific revision, so BinderHub will use the GitHub API to look up what revision that name corresponds to. You can use tags, branch names or actual revisions for this part. What things you can put here depends on the first part of the URL. For example if you are referring to a plain `git` repository you can’t put a name like `master` because there is no API BinderHub can talk to in order to find out what actual revision that name corresponds to.

This covers the basic parts of a Binder launch link. Go and experiment with them for a bit to get the hang out it. They look intimidating at first but there is method to the madness. I promise.

### Advanced patterns

There are a two more advanced things you can do with Binder launch links once you are happy with how the basics work.

#### Directly opening a particular file

Sometimes you want to take people directly to a particular notebook or other file when they click you Binder launch link. For example [https://mybinder.org/v2/gh/binder-examples/requirements/master?filepath=index.ipynb](https://mybinder.org/v2/gh/binder-examples/requirements/master?filepath=index.ipynb) will take you straight to the `index.ipynb` notebook in the example repository. By specifying the `filepath` parameter you can send people to a view of (almost any) file in your repository. Make sure the path you specify is relative to the root of your repository.

#### Using a different user interface

Sometimes you want to send people straight to RStudio or Jupyter Lab instead of the classic notebook interface. Let’s use the R example repository to illustrate this.

The basic [https://mybinder.org/v2/gh/binder-examples/r/master](https://mybinder.org/v2/gh/binder-examples/r/master) launch link will take you to the classic notebook UI. Compare that to [https://mybinder.org/v2/gh/binder-examples/r/master?urlpath=rstudio](https://mybinder.org/v2/gh/binder-examples/r/master?urlpath=rstudio) which will take you to the RStudio interface.

If you open each of the two links in a new tab and wait for your Binders to launch you will see that the URL in your browsers will be different. For the basic launch link you will be on a page similar to [https://hub.mybinder.org/user/binder-examples-r-b2xb8mb5/tree](https://hub.mybinder.org/user/binder-examples-r-b2xb8mb5/tree) and for the RStudio one you will be at [https://hub.mybinder.org/user/binder-examples-r-5r9dl00p/rstudio/](https://hub.mybinder.org/user/binder-examples-r-5r9dl00p/rstudio/). By specifying the `urlpath` parameter you replace the last part of the default URL (`tree`) with the value you specify.

For more examples on configuring user interfaces check [https://mybinder.readthedocs.io/en/latest/howto/user\_interface.html#user-interface](https://mybinder.readthedocs.io/en/latest/howto/user_interface.html#user-interface)

You have a lot of control on what users see depending on how you construct your Binder launch link. You can explore the possibilities via the form on [http://mybinder.org/:](http://mybinder.org/:) watch how the generated link changes depending on which options you select from the drop down menus and which form fields you fill in.

(this post is a wiki post, this means you can directly edit it if you find typos or think a sentence could be clearer. Happy editing!)

---

<div class="post-metadata">

**Author:** ![betatim](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/betatim/32/10_2.png) [@betatim](https://discourse.jupyter.org/u/betatim)\
**Post date:** [March 31, 2019, 5:18pm UTC](https://discourse.jupyter.org/t/how-do-binder-launch-links-work-or-wait-i-can-do-that-with-a-link/647/2 "2019-03-31T17:18:37Z")

</div>

Either a new post or addition to the above: some “best practices” like using a tag to always launch the same version without users having to wait for a build because `master` was updated.

---

<div class="post-metadata">

**Author:** ![psychemedia](https://yyz1.discourse-cdn.com/flex031/user_avatar/discourse.jupyter.org/psychemedia/32/24_2.png) [@psychemedia](https://discourse.jupyter.org/u/psychemedia)\
**Post date:** [April 1, 2019, 2:50pm UTC](https://discourse.jupyter.org/t/how-do-binder-launch-links-work-or-wait-i-can-do-that-with-a-link/647/3 "2019-04-01T14:50:55Z")

</div>

I think it would be useful to give literal examples of the similarities and differences between `urlpath` and `filepath`.