First steps
It's simple:
- tell your browser to use PyScript, then,
- tell PyScript how to run your Python code.
That's it!
For the browser to use PyScript, simply add a <script>
tag, whose src
attribute references a CDN url for pyscript.core
, to your HTML document's
<head>
. We encourage you to add a reference to optional PyScript related
CSS:
<!doctype html>
<html>
<head>
<!-- Recommended meta tags -->
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1.0">
<!-- PyScript CSS -->
<link rel="stylesheet" href="https://pyscript.net/releases/2024.9.2/core.css">
<!-- This script tag bootstraps PyScript -->
<script type="module" src="https://pyscript.net/releases/2024.9.2/core.js"></script>
</head>
<body>
<!-- your code goes here... -->
</body>
</html>
There are two ways to tell PyScript how to find your code.
- With a standard HTML
<script>
tag whosetype
attribute is eitherpy
(for Pyodide) ormpy
(for MicroPython). This is the recommended way. - Via the bespoke
<py-script>
(Pyodide) and<mpy-script>
(MicroPython) tags. Historically,<py-script>
used to be the only way to reference your code.
These should be inserted into the <body>
of your HTML document.
In both cases either use the src
attribute to reference a Python
file containing your code, or inline your code between the opening and closing
tags. We recommend you use the src
attribute method, but retain the
ability to include code between tags for convenience.
Here's a <script>
tag with a src
attribute containing a URL
pointing to a main.py
Python file.
...and here's a <py-script>
tag with inline Python code.
<py-script>
import sys
from pyscript import display
display(sys.version)
</py-script>
The <script>
and <py-script>
/ <mpy-script>
tags may have the following
attributes:
src
- the content of the tag is ignored and the Python code in the referenced file is evaluated instead. This is the recommended way to reference your Python code.config
- your code will only be evaluated after the referenced configuration has been parsed. Since configuration can be JSON or a TOML file,config='{"packages":["numpy"]}'
andconfig="./config.json"
orconfig="./config.toml"
are all valid.async
- set this flag to"false"
so your code won't run within a top level await (the default behaviour).
Warning
This behaviour changed in version 2024.8.2.
PyScript now uses a top level await by default.
You used to have to include the async
flag to enable this. Now, instead,
use async="false"
to revert the behaviour back to the old default
behaviour of synchronous evaluation.
We made this change because many folks were await
-ing functions and
missing or not realising the need for the (old) async
attribute. Hence
the flip in behaviour.
worker
- a flag to indicate your Python code is to be run on a web worker instead of the "main thread" that looks after the user interface.target
- the id or selector of the element where calls todisplay()
should write their values.terminal
- a traditional terminal is shown on the page. As with conventional Python,print
statements output here. If theworker
flag is set the terminal becomes interactive (e.g. use theinput
statement to gather characters typed into the terminal by the user).service-worker
- an optional attribute that allows you to slot in a custom service worker (such asmini-coi.js
) to fix header related problems that limit the use of web workers. This rather technical requirement is fully explained in the section on web workers.
Warning
The packages
setting used in the example configuration shown above is
for Pyodide using PyPI.
When using MicroPython, and because MicroPython doesn't support code packaged on PyPI, you should use a valid URL to a MicroPython friendly package.
For more information please refer to the packages section of this user guide.
Question
Why do we recommend use of the <script>
tag with a src
attribute?
Within the HTML standard,
the <script>
tag is used to embed executable code. Its use case
completely aligns with our own, as does its default behaviour.
By referencing a separate Python source file via the src
attribute, your
code is just a regular Python file your code editor will understand. Python
code embedded within a <script>
tag in an HTML file won't benefit from
the advantages code editors bring: syntax highlighting, code analysis,
language-based contextual awareness and perhaps even an AI co-pilot.
Both the <py-script>
and <mpy-script>
tags with inline code are
web components
that are not built into the browser. While they are convenient, there is
a performance cost to their use.
Info
The browser's tab displaying the website running PyScript is an isolated computing sandbox. Define the Python environment in which your code will run with configuration options (discussed later in this user guide).
Tip
If you want to run code on both the main thread and in a worker, be explicit and use separate tags.
<script type="mpy" src="main.py"></script> <!-- on the main thread -->
<script type="py" src="worker.py" worker config="pyconfig.toml"></script> <!-- on the worker -->
Notice how different interpreters can be used with different configurations.