Skip to main content

A Filesystem-like mult-contents manager backend for Jupyter

Project description


azure ci status appveyor ci status (telamonian fork) pypi package npm package

A plugin for JupyterLab that lets you set up and use as many filebrowsers as you like, connected to whatever local and/or remote filesystem-like resources you want.

The backend is built on top of PyFilesystem, while the frontend is built on top of JupyterLab Filetree.


pip install jupyter-fs


Add the following to your jupyter_notebook_config.json:

  "NotebookApp": {
    "contents_manager_class": "jupyterfs.metamanager.MetaManager",
    "nbserver_extensions": {
      "jupyterfs": true

Simple use (no auth/credentials)

Add specifications for additional contents managers in your user settings (in the Settings menu under Advanced Settings Editor -> jupyter-fs). Here's an example config that sets up several new filebrowsers side-by-side:

  "resources": [
      "name": "root at test dir",
      "url": "osfs:///Users/foo/test"
      "name": "s3 test bucket",
      "url": "s3://test"
      "name": "samba guest share",
      "url": "smb://guest@"

You should see your new filebrowsers pop up in the left-hand sidebar instantly when you save your settings:

Use with auth/credentials

Any stretch of a "url" that is enclosed in double-brackets {{VAR}} will be treated as a template, and will be handled by jupyter-fs's auth system. For example, you can pass a username/password to the "samba guest share" resource in the Simple use example above by modifying its "url" like so:

  "resources": [

      "name": "samba share",
      "url": "smb://{{user}}:{{passwd}}@"

When you save the above "resouces" config, a dialog box will pop asking for the username and passwd values:

Once you enter those values and hit ok, the new filebrowsers will then immediately appear in the sidebar:

The auth dialog will only appear when needed

The jupyter-fs auth dialog will only appear when:

  • JupyterLab first loads, if any fs resources reqiure auth
  • a new fs resouce is added that requires auth, or its "url" field is modified

Supported filesystems

The type of resource each filebrowser will point to is determined by the protocol at the start of its url:

  • osfs: os filesystem. The will open a new view of your local filesystem, with the specified root
  • s3: opens a filesystem pointing to an Amazon S3 bucket
  • smb: opens a filesystem pointing to a Samba share

jupyter-fs can open a filebrowser pointing to any of the diverse resources supported by PyFilesystem. Currently, we test only test the S3 and smb/samba backends as part of our CI, so your milleage may vary with the other PyFilesystem backends.

The filesystem url

The "url" field jupyter-fs config is based on the PyFilesystem opener url standard. For more info on how to write these urls, see the documentation of the relevant PyFilesystem plugin:

Server-side settings

If you prefer to set up your filesystem resources in the server-side config, you can do so. For example, you can set up a local filesystem by adding the following to your

c.jupyterfs.specs = [
        "name": "local_test",
        "url": "osfs:///Users/foo/test"

Any filesystem specs given in the server-side config will be merged with the specs given in a user's settings.


See for guidelines.


This software is licensed under the Apache 2.0 license. See the LICENSE and AUTHORS files for details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jupyter-fs-0.0.3.tar.gz (660.2 kB view hashes)

Uploaded Source

Built Distribution

jupyter_fs-0.0.3-py2.py3-none-any.whl (113.6 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page