{"id":13606167,"url":"https://github.com/willkessler/jupyterterminals","last_synced_at":"2025-10-16T22:43:08.615Z","repository":{"id":47880411,"uuid":"245849686","full_name":"willkessler/jupyterterminals","owner":"willkessler","description":"Jupyter plugin to support inline terminal shells along with buttons to control them","archived":false,"fork":false,"pushed_at":"2023-01-05T23:10:50.000Z","size":1080,"stargazers_count":12,"open_issues_count":2,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-15T07:47:31.028Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/willkessler.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-08T16:36:18.000Z","updated_at":"2024-06-28T05:50:42.000Z","dependencies_parsed_at":"2023-02-04T22:46:43.891Z","dependency_job_id":null,"html_url":"https://github.com/willkessler/jupyterterminals","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willkessler%2Fjupyterterminals","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willkessler%2Fjupyterterminals/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willkessler%2Fjupyterterminals/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willkessler%2Fjupyterterminals/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/willkessler","download_url":"https://codeload.github.com/willkessler/jupyterterminals/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248539745,"owners_count":21121227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T19:01:06.682Z","updated_at":"2025-10-16T22:43:08.520Z","avatar_url":"https://github.com/willkessler.png","language":"JavaScript","funding_links":[],"categories":["Jupyter拓展"],"sub_categories":[],"readme":"# Add Linux Terminals, Inline, in Jupyter Notebooks\n\n![intro_movie](./readme_gifs/intro.gif)\n\n### What's This Good For?\n\nUsing this plugin, you can insert terminal cells (shells) using a\nbutton added to your Jupyter toolbar.  This is useful for teaching (we\nuse the facility at Udacity), or anywhere where you just want a\nconvenient interactive shell terminal inlined with the rest of your\nJupyter notebook cells. (Normally to access terminals in Jupyter, you\nmust leave your notebook).\n\n### Features\n\n* Any terminal cell can be \"Reset\" which destroys that shell and creates a new cell, via a link under the cell. (Use this if the terminal locks up somehow.)\n* The shells `pwd` is set to the directory containing the current\nnotebook. If you click the \"Jump to Notebook's Dir\" link you can make the\nterminal go back to the directory where the notebook is located.\n* Remove Terminal cells by simply deleting them.\n* Set the number of lines displayed in a terminal cell by editing the cell's metadata.\n* Set an initial command to run when the terminal is first opened, also available in the cell's metadata.\n\n[ _Please note: Each terminal cell is connected to a separate bash shell. You can see these terminals in Jupyter's \"Running\" tab.  If you reload the notebook, you will connect to the same Jupyter terminals you loaded earlier, with their history intact (although you may not see the previous output in that terminal).  If you delete a terminal cell, the Jupyter terminal will continue to live for the life of the server until you shut it down from the \"Running\" tab._]\n\nTo configure the terminal cell you can edit its metadata. It will look something like this:\n\n```\n{\n  \"terminalCellId\": \"id_5gnrnaq\",\n  \"terminalConfig\": {\n    \"initialCommand\": \"\",\n    \"rows\": 6,\n    \"startingDirectory\": \"samples/ai_on_edge\",\n    \"terminalId\": \"id_j4fpm1t\",\n    \"type\": \"terminal\"\n  }\n}\n```\n\n* You can set the number of rows displayed for the terminal with the `rows` field. \n* You can set an initial command to run every time the terminal loads, with the `initialCommand` field. (Note that a carriage return will be added to this command automatically.)\n* You can set the startingDirectory for this terminal, to something other than the one containing this notebook.\n* Do not change the `terminalId` or `type` fields.\n\n### Terminal Control Buttons\n\n![buttons_movie](./readme_gifs/buttons.gif)\n\nYou can also add buttons to markdown cells that can send commands to\nterminals. This may be useful when you're teaching a topic and want to\nset up a button that enters a long or complex command you want\nstudents to see demonstrated, for instance, a `gcc` command with a lot of arguments.\n\nJust click the \"Create Control Button\" link under a\nterminal.  This will add a button labeled \"Terminal Button\" to the\nnext cell below the Terminal cell, or will insert a new markdown cell\nif the next cell is a code cell (or there is no next cell). By default \nthe buttons will just run a simple Hello World message to the terminal.\nTo change the command that is run in the terminal, edit the metadata for\nthe cell containing the button. You will find metadata like the following:\n\n```\n{\n  \"terminalCellId\": \"id_dut2ahg\",\n  \"terminalConfig\": {\n    \"buttonsConfig\": {\n      \"id_kk1vk6w\": {\n        \"addCr\": \"true\",\n        \"command\": \"echo \\\"Hello World!\\\"\",\n        \"targetCellId\": \"id_38fegvu\"\n      }\n    },\n    \"type\": \"markdown\"\n  }\n}\n```\n\nEach button you create will have an entry in the metadata you can\nmodify to set the command the button runs in the terminal.  \n\n* If `addCr` is true, then the plugin will also add a carriage return after the\ncommand when it is sent to the terminal.  \n* The `targetCellId` is the ID of the terminal that the button will send the command to. By default\nthis is the terminal you used to create the button in the first place.\n\nIf you want to create more than one button to control a terminal, you\ncan. Each will get a unique ID. To see the IDs for each button, you\ncan edit the markdown of the cell containing the button. Each button\nis described by some HTML in the markdown cell, and the class attached\nto the button will reveal to you its ID. For instance, for the button\nshown above,\n\n```\n\u003cbutton class=\"terminal-button-id_kk1vk6w\"\u003eRun Command\u003c/button\u003e\n```\n\nIf you don't have the plugin installed, then terminal cells will\nappear as markdown cells with an explanatory message on how to install\nthe plugin in them. When you distribute notebooks with Jupyter\nTerminals, the recipient will also need to install the plugin to see\n(and use) them.\n\n### Trying it out safely\n\nIf you want to just try out the plugin without installing it you can just this Binder link:\n\n* [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/willkessler/jupyterterminals/master?filepath=samples%2FJupyterTerminalsDemo.ipynb) \u003ca href=\"https://mybinder.org/v2/gh/willkessler/jupyterterminals/master?filepath=samples%2FJupyterTerminalsDemo.ipynb\"\u003eJupyter Terminals Demo\u003c/a\u003e\n\nOr, you can try a local Docker setup:\n\n```\njupyterterminals/build_and_run.sh 9991\n```\n\nand then surf to `http://localhost:9991?token=\u003ctoken\u003e` and provide the token shown in Docker's output (which will look something like this):\n\n```\n To access the notebook, open this file in a browser:\n        file:///home/jovyan/.local/share/jupyter/runtime/nbserver-6-open.html\n    Or copy and paste one of these URLs:\n        http://cdb36b52eeac:8888/?token=d662c994e7f5ae76dbf3e05f95a4fc1a435ec46475e184f8\n     or http://127.0.0.1:8888/?token=d662c994e7f5ae76dbf3e05f95a4fc1a435ec46475e184f8\n```\n\nIn the example output above,  you wouldn't do what Jupyter is telling you, because 8888 is not the port you just provided. Since `9991` is the port you passed to \nthe `build_and_run.sh` script, so you will want to surf to `http://127.0.0.1:9991/?token=d662c994e7f5ae76dbf3e05f95a4fc1a435ec46475e184f8`.  Then you can just \ncreate a notebook as you normally would to try out the plugin.\n\n### Installation\n\nInstall the plugin with :\n\n`pip install jupyterterminals`\n\nor\n\n`conda install -c willkessler jupyterterminals`\n\n### Limitations\n\nThis plugin has not been configured to work on Windows systems running Jupyter.\nThis is planned for a future release, however.\n\n### TODOs\n\n* Add a global metadata config so we can turn off the display of \"Create Control Button\" link.\n\n### Related Software\n\nInlined Terminals are included by default in \u003ca\nstyle=\"font-weight:bold\" target=\"_blank\"\nhref=\"https://www.github.com/willkessler/jupytergraffiti\"\u003eJupyter\nGraffiti\u003c/a\u003e, which also allows you to add popup tips to any text in\nyour notebook, and create interactive screen recordings to help you\nteach topics using Jupyter Notebooks.\n\nTake a look at \u003ca style=\"font-weight:bold\" target=\"_blank\"\nhref=\"https://www.github.com/willkessler/jupytergraffiti\"\u003eJupyter\nGraffiti\u003c/a\u003e to learn more about what it can do for you!\n\n(Do not use Jupyter Terminals and Jupyter Graffiti at the same time: they will conflict.)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillkessler%2Fjupyterterminals","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwillkessler%2Fjupyterterminals","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillkessler%2Fjupyterterminals/lists"}