Description

Add runnable Python code blocks to your notes!

Additional Information

Links:	Repository Homepage View source
Maintainers:	will.english
Version:	1.0.0
Minimum app version:	3.3
Downloads: This version:	27
Last updated:	2026-04-14T16:50:11Z

Jopyter Notebook - Joplin Plugin

Add runnable Python code blocks to your Joplin notes!

Jopyter brings Jupyter notebook functionality directly into Joplin, allowing you to write, execute, and display Python code with rich output including plots, images, and formatted text right in your notes.

Features

Execute Python code blocks directly in Joplin notes
Rich output support including:
- Text output (stdout/stderr)
- Images and plots (matplotlib, seaborn, etc.)
- HTML and Markdown rendering
- Error handling with full tracebacks
Multiple execution modes:
- Run all Python blocks in a note
- Run the current block (cursor-based)
- Run specific blocks with custom kernels
Persistent kernels for maintaining variable state between executions
Keyboard shortcuts for quick execution
Context menus and toolbar integration
Customizable settings for Python path and kernel configuration
Automatic demo notebook with comprehensive examples and tutorials

Prerequisites

Before using Jopyter, ensure you have:

Python 3.6+ installed on your system
Required Python packages:
```
pip install jupyter_client ipykernel
```

Installation

Download the latest .jpl file from the releases page
In Joplin, go to Tools → Options → Plugins
Click Install from file and select the downloaded .jpl file
Restart Joplin
Demo notebook: A "Jopyter Notebook" folder will be automatically created at the top level with a comprehensive demo note containing examples and tutorials

Configuration

After installation, configure Jopyter:

Go to Tools → Options → Plugins → Jopyter
Set the following options:
- Python executable: Path to your Python interpreter (e.g., /usr/bin/python3)
- Default kernel name: Kernel name to use (default: python3)
- Working directory: Optional working directory for code execution

Platform-Specific Python Paths

Linux: /usr/bin/python3 or ~/miniconda3/envs/myenv/bin/python
macOS: /opt/homebrew/bin/python3 or /usr/local/bin/python3
Windows: C:\Users\you\miniconda3\envs\myenv\python.exe

Usage

Creating Python Code Blocks

Method 1: Using the Menu

Place your cursor where you want the code block
Go to Tools → Jopyter → Insert Python code block
Or use the keyboard shortcut: Ctrl+Alt+P (Windows/Linux) or Cmd+Alt+P (macOS)

Method 2: Manual Creation

Create a code block with the following syntax:

```python kernel=python3
# Your Python code here
print("Hello, Jopyter!")
```

Executing Code

Run All Python Blocks

Menu: Tools → Jopyter → Run all Python blocks
Toolbar: Click the Python icon in the editor toolbar
Keyboard: Use the command palette (Ctrl+Shift+P / Cmd+Shift+P)

Run Current Block

Keyboard: Ctrl+Shift+Enter (Windows/Linux) or Cmd+Shift+Enter (macOS)
Context Menu: Right-click in a Python block → "Run current Python block"
Menu: Tools → Jopyter → Run current Python block

Advanced Features

Custom Kernels

Specify different kernels for different code blocks:

```python kernel=myenv
import pandas as pd
# This uses the 'myenv' kernel
```

Working Directory

Set a custom working directory in the plugin settings to run code from a specific location.

Rich Output Examples

```python
import matplotlib.pyplot as plt
import numpy as np

# Create a simple plot
x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.plot(x, y)
plt.title('Sine Wave')
plt.show()
```

Managing Outputs

Clear all outputs: Tools → Jopyter → Clear all Jopyter outputs in note
Restart kernel: Tools → Jopyter → Restart Python kernel
Create demo notebook: Tools → Jopyter → Create Jopyter demo notebook (creates the tutorial notebook)
Force create demo notebook: Tools → Jopyter → Force create Jopyter demo notebook (recreate) (deletes existing and creates fresh)
Find demo notebook location: Tools → Jopyter → Find Jopyter demo notebook location (shows where the notebook is located)
Open demo notebook: Tools → Jopyter → Open Jopyter demo notebook (opens the demo note)

Screenshots

To help users understand how to use Jopyter, please take the following screenshots:

1. Plugin Installation

File: screenshots/installation.png

Screenshot of Joplin's plugin installation dialog
Show the "Install from file" button and file selection

2. Plugin Settings

File: screenshots/settings.png

Screenshot of Tools → Options → Plugins → Jopyter
Show the three configuration fields:
- Python executable path
- Default kernel name
- Working directory

3. Menu Integration

File: screenshots/menu.png

Screenshot of the Tools → Jopyter menu
Show all available commands:
- Insert Python code block
- Run all Python blocks
- Run current Python block
- Restart Python kernel
- Clear all Jopyter outputs in note

4. Toolbar Button

File: screenshots/toolbar.png

Screenshot of the editor toolbar
Highlight the Python icon button for running all blocks

5. Context Menu

File: screenshots/context-menu.png

Screenshot of right-clicking in a Python code block
Show the context menu options for Jopyter

6. Basic Code Execution

File: screenshots/basic-execution.png

Screenshot of a simple Python code block before execution
Show the code and the output after running

7. Rich Output Example

File: screenshots/rich-output.png

Screenshot showing matplotlib plot output
Include both the code block and the rendered plot

8. Error Handling

File: screenshots/error-handling.png

Screenshot of a Python code block with an error
Show the error output with traceback

9. Multiple Code Blocks

File: screenshots/multiple-blocks.png

Screenshot of a note with multiple Python code blocks
Show different execution states (some run, some not)

10. Keyboard Shortcuts

File: screenshots/keyboard-shortcuts.png

Screenshot of Joplin's keyboard shortcuts settings
Highlight the Jopyter-specific shortcuts

Keyboard Shortcuts

Action	Windows/Linux	macOS
Insert Python code block	`Ctrl+Alt+P`	`Cmd+Alt+P`
Run current Python block	`Ctrl+Shift+Enter`	`Cmd+Shift+Enter`

Troubleshooting

Plugin Crashes on Startup

If Joplin crashes when starting with Jopyter enabled:

Check Python installation: Ensure Python 3.6+ is installed
Install required packages:
```
pip install jupyter_client ipykernel
```
Verify Python path: Check that the Python executable path in settings is correct
Check Joplin logs: Enable developer tools (Help → Toggle Developer Tools) to see error messages

Code Execution Issues

Module not found: Install required Python packages in your environment
Permission errors: Check that the working directory is accessible
Kernel issues: Try restarting the kernel or using a different kernel name

Output Not Displaying

Images not showing: Ensure matplotlib/seaborn plots use plt.show()
HTML not rendering: Check that the output is valid HTML
Text formatting: Use proper markdown syntax in your output

Development

Building from Source

Clone the repository:

git clone https://github.com/Dubascudes/JopyterPlugin.git
cd JopyterPlugin

Install dependencies:
```
npm install
```
Build the plugin:
```
npm run dist
```
The built plugin will be in the publish/ directory

Project Structure

src/
├── index.ts          # Main plugin logic
├── editor.ts         # CodeMirror editor integration
├── manifest.json     # Plugin manifest
└── python/
    └── bridge.py     # Python-Jupyter bridge script

Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Website: willenglish.tech

Changelog

v1.0.0

Initial release
Basic Python code execution
Rich output support
Multiple execution modes
Keyboard shortcuts and context menus
Customizable settings

Made with ❤️ for the Joplin community