2021-08-12 09:39:13 +00:00
|
|
|
# Using Pyodide
|
|
|
|
|
|
2022-06-22 03:15:37 +00:00
|
|
|
Pyodide may be used in a web browser or a backend JavaScript environment.
|
2021-08-12 09:39:13 +00:00
|
|
|
|
|
|
|
|
## Web browsers
|
|
|
|
|
|
2022-06-22 03:15:37 +00:00
|
|
|
To use Pyodide in a web page you need to load `pyodide.js` and initialize
|
|
|
|
|
Pyodide with {any}`loadPyodide <globalThis.loadPyodide>`.
|
2021-08-12 09:39:13 +00:00
|
|
|
|
|
|
|
|
```html-pyodide
|
|
|
|
|
<!DOCTYPE html>
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
2022-05-30 01:26:40 +00:00
|
|
|
<script src="{{PYODIDE_CDN_URL}}pyodide.js"></script>
|
2021-08-12 09:39:13 +00:00
|
|
|
</head>
|
|
|
|
|
<body>
|
|
|
|
|
<script type="text/javascript">
|
|
|
|
|
async function main(){
|
2022-03-21 05:44:54 +00:00
|
|
|
let pyodide = await loadPyodide();
|
2021-08-12 09:39:13 +00:00
|
|
|
console.log(pyodide.runPython("1 + 2"));
|
|
|
|
|
}
|
|
|
|
|
main();
|
|
|
|
|
</script>
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
|
|
|
|
```
|
|
|
|
|
|
2022-06-22 03:15:37 +00:00
|
|
|
See the {ref}`quickstart` for a walk-through tutorial as well as
|
2021-08-12 09:39:13 +00:00
|
|
|
{ref}`loading_packages` and {ref}`type-translations` for a more in depth
|
|
|
|
|
discussion about existing capabilities.
|
|
|
|
|
|
|
|
|
|
You can also use the [Pyodide NPM
|
|
|
|
|
package](https://www.npmjs.com/package/pyodide) to integrate Pyodide into your
|
|
|
|
|
application.
|
|
|
|
|
|
|
|
|
|
```{note}
|
|
|
|
|
To avoid confusion, note that:
|
|
|
|
|
- `cdn.jsdelivr.net/pyodide/` distributes Python packages built with Pyodide as well as `pyodide.js`
|
2022-01-10 23:44:13 +00:00
|
|
|
- `cdn.jsdelivr.net/npm/pyodide@0.19.0/` is a mirror of the Pyodide NPM package, which includes none of the WASM files
|
2021-08-12 09:39:13 +00:00
|
|
|
```
|
|
|
|
|
|
2021-08-12 10:43:50 +00:00
|
|
|
### Supported browsers
|
|
|
|
|
|
|
|
|
|
Pyodide works in any modern web browser with WebAssembly support.
|
|
|
|
|
|
|
|
|
|
**Tier 1** browsers are tested as part of the test suite with continuous integration,
|
|
|
|
|
|
|
|
|
|
| Browser | Minimal supported version | Release date |
|
|
|
|
|
| ------- | ------------------------- | --------------- |
|
|
|
|
|
| Firefox | 70.0 | 22 October 2019 |
|
|
|
|
|
| Chrome | 71.0 | 4 December 2018 |
|
|
|
|
|
|
2022-03-05 00:09:51 +00:00
|
|
|
Chrome 89 and 90 have bugs in the webassembly compiler which makes using Pyodide
|
|
|
|
|
with them unstable. Known problems occur in numpy and have been observed
|
2022-03-08 05:51:20 +00:00
|
|
|
occasionally in other packages. See {issue}`1384`.
|
2022-03-05 00:09:51 +00:00
|
|
|
|
2021-08-12 10:43:50 +00:00
|
|
|
```{note}
|
|
|
|
|
Latest browser versions generally provide more reliable WebAssembly support
|
|
|
|
|
and will run Pyodide faster, so their use is recommended.
|
|
|
|
|
```
|
|
|
|
|
|
2021-11-14 20:47:49 +00:00
|
|
|
**Tier 2** browsers are known to work, but they are not systematically tested in
|
2021-08-12 10:43:50 +00:00
|
|
|
Pyodide,
|
|
|
|
|
|
|
|
|
|
| Browser | Minimal supported version | Release date |
|
|
|
|
|
| ------- | ------------------------- | ----------------- |
|
2022-06-02 17:09:54 +00:00
|
|
|
| Safari | 14.0 | 15 September 2020 |
|
|
|
|
|
| Edge | 80 | 26 February 2020 |
|
2021-08-12 10:43:50 +00:00
|
|
|
|
|
|
|
|
Other browsers with WebAssembly support might also work however they are not
|
|
|
|
|
officially supported.
|
|
|
|
|
|
2021-08-12 09:39:13 +00:00
|
|
|
## Web Workers
|
|
|
|
|
|
2021-11-14 20:47:49 +00:00
|
|
|
By default, WebAssembly runs in the main browser thread, and it can make UI
|
|
|
|
|
non-responsive for long-running computations.
|
2021-08-12 09:39:13 +00:00
|
|
|
|
|
|
|
|
To avoid this situation, one solution is to run {ref}`Pyodide in a WebWorker <using_from_webworker>`.
|
|
|
|
|
|
|
|
|
|
## Node.js
|
|
|
|
|
|
2022-07-16 09:33:18 +00:00
|
|
|
```{note}
|
|
|
|
|
The following instructions have been tested with Node.js 18.5.0. To use
|
|
|
|
|
Pyodide with older versions of Node, you might need to use additional command line
|
|
|
|
|
arguments, see below.
|
|
|
|
|
```
|
2021-08-12 09:39:13 +00:00
|
|
|
|
2022-07-16 09:33:18 +00:00
|
|
|
It is now possible to install the
|
|
|
|
|
[Pyodide npm package](https://www.npmjs.com/package/pyodide) in Node.js. To
|
|
|
|
|
follow these instructions you need at least Pyodide 0.21.0.
|
|
|
|
|
You can explicitly ask npm to use
|
|
|
|
|
the alpha version:
|
2021-08-12 09:39:13 +00:00
|
|
|
|
|
|
|
|
```
|
2022-07-16 09:33:18 +00:00
|
|
|
$ npm install "pyodide@>=0.21.0-alpha.2"
|
2021-08-12 09:39:13 +00:00
|
|
|
```
|
|
|
|
|
|
2022-07-16 09:33:18 +00:00
|
|
|
Once installed, you can run the following simple script:
|
2021-08-12 09:39:13 +00:00
|
|
|
|
|
|
|
|
```js
|
2022-07-16 09:33:18 +00:00
|
|
|
// hello_python.js
|
|
|
|
|
const { loadPyodide } = require("pyodide");
|
|
|
|
|
|
|
|
|
|
async function hello_python() {
|
|
|
|
|
let pyodide = await loadPyodide();
|
|
|
|
|
return pyodide.runPythonAsync("1+1");
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
hello_python().then((result) => {
|
|
|
|
|
console.log("Python says that 1+1 =", result);
|
|
|
|
|
});
|
2021-08-12 09:39:13 +00:00
|
|
|
```
|
|
|
|
|
|
2022-07-16 09:33:18 +00:00
|
|
|
```
|
|
|
|
|
$ node hello_python.js
|
|
|
|
|
Loading distutils
|
|
|
|
|
Loaded distutils
|
|
|
|
|
Python initialization complete
|
|
|
|
|
Python says that 1+1= 2
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Or you can use the REPL. To start the Node.js REPL with support for top level
|
|
|
|
|
await, use `node --experimental-repl-await`:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
$ node --experimental-repl-await
|
|
|
|
|
Welcome to Node.js v18.5.0.
|
|
|
|
|
Type ".help" for more information.
|
|
|
|
|
> const { loadPyodide } = require("pyodide");
|
|
|
|
|
undefined
|
|
|
|
|
> let pyodide = await loadPyodide();
|
|
|
|
|
Loading distutils
|
|
|
|
|
Loaded distutils
|
|
|
|
|
Python initialization complete
|
|
|
|
|
undefined
|
|
|
|
|
> await pyodide.runPythonAsync("1+1");
|
|
|
|
|
2
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Node.js versions <0.17
|
|
|
|
|
|
|
|
|
|
- `Node.js` versions 14.x and 16.x: to use certain features of Pyodide you
|
|
|
|
|
need to manually install `node-fetch`, e.g. by doing `npm install node-fetch`.
|
|
|
|
|
|
|
|
|
|
- `Node.js v14.x`: you need to pass the option `--experimental-wasm-bigint`
|
|
|
|
|
when starting Node. Note that this flag is not documented by `node --help`
|
|
|
|
|
and moreover, if you pass `--experimental-wasm-bigint` to node >14 it is an
|
|
|
|
|
error:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
$ node -v
|
|
|
|
|
v14.20.0
|
|
|
|
|
|
|
|
|
|
$ node --experimental-wasm-bigint hello_python.js
|
|
|
|
|
warning: no blob constructor, cannot create blobs with mimetypes
|
|
|
|
|
warning: no BlobBuilder
|
|
|
|
|
Loading distutils
|
|
|
|
|
Loaded distutils
|
|
|
|
|
Python initialization complete
|
|
|
|
|
Python says that 1+1= 2
|
2021-08-12 09:39:13 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
```{eval-rst}
|
|
|
|
|
.. toctree::
|
|
|
|
|
:hidden:
|
|
|
|
|
|
|
|
|
|
webworker.md
|
2022-01-04 15:46:00 +00:00
|
|
|
loading-custom-python-code.md
|
2022-05-04 10:43:34 +00:00
|
|
|
file-system.md
|
2021-08-12 09:39:13 +00:00
|
|
|
```
|
