Lerking/python-appimage
1
0
Fork 0
mirror of https://github.com/niess/python-appimage.git synced 2025-07-21 12:51:16 +02:00
Code Issues Packages Projects Releases Wiki Activity

Clean the documentation

Browse Source
This commit is contained in:
Valentin Niess
2025-05-23 12:40:59 +02:00
parent 19fe0dbab9
commit 839cbc3fd4
6 changed files with 219 additions and 203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
README.md
View File

@@ -5,18 +5,18 @@ _Ready to use AppImages of Python are available as GitHub [releases][RELEASES]._
## Quickstart ## Quickstart
We provide relocatable Python runtimes as [AppImages][APPIMAGE] for Linux We provide relocatable Python runtimes in the form of [AppImages][APPIMAGE] for
systems. These runtimes are extracted from [Manylinux][MANYLINUX] Docker images, Linux systems. These runtimes are extracted from [Manylinux][MANYLINUX] Docker
and they are available as GitHub [releases][RELEASES]. Our Python AppImages are images and are available as GitHub [releases][RELEASES]. Our Python AppImages
updated weekly, on every Sunday. are updated weekly, on every Sunday.
Instructions for _installing_ and running _Python AppImages_ are provided on Instructions for _installing_ and running _Python AppImages_ can be found on
[Read the Docs][READTHEDOCS]. [Read the Docs][READTHEDOCS].
In addition, the online documentation describes the [`python-appimage`][PYPI] The online documentation also describes the [`python-appimage`][PYPI] utility
utility, for application developers. This utility can facilitate the building of for application developers. This utility can facilitate the development of
Python apps, given an existing Python AppImage and a recipe folder. Python applications, provided you have an existing Python AppImage and a recipe
[Examples][APPLICATIONS] of recipes are available from GitHub. folder. [Examples][APPLICATIONS] of recipes are available on GitHub.
## Projects using [`python-appimage`][GITHUB] ## Projects using [`python-appimage`][GITHUB]

2
docs/include/references.md
View File

@@ -12,7 +12,9 @@
[GITHUB]: {{ config.repo_url }} [GITHUB]: {{ config.repo_url }}
[LINUXDEPLOY]: https://github.com/linuxdeploy/linuxdeploy/ [LINUXDEPLOY]: https://github.com/linuxdeploy/linuxdeploy/
[MANYLINUX]: https://github.com/pypa/manylinux/ [MANYLINUX]: https://github.com/pypa/manylinux/
[NUMPY]: https://numpy.org/
[PATCHELF]: https://github.com/NixOS/patchelf/ [PATCHELF]: https://github.com/NixOS/patchelf/
[PEP_425]: https://peps.python.org/pep-0425/
[PYPI]: https://pypi.org/project/python-appimage/ [PYPI]: https://pypi.org/project/python-appimage/
[RELEASES]: {{ config.repo_url }}releases/ [RELEASES]: {{ config.repo_url }}releases/
[SHEBANG]: https://en.wikipedia.org/wiki/Shebang_(Unix)/ [SHEBANG]: https://en.wikipedia.org/wiki/Shebang_(Unix)/

2
docs/mkdocs.yml
View File

@@ -10,7 +10,7 @@ docs_dir: src
nav: nav:
- Python AppImages: index.md - Python AppImages: index.md
- Developers corner: apps.md - Developers' corner: apps.md
theme: theme:
name: readthedocs name: readthedocs

231
docs/src/apps.md
View File

@@ -10,157 +10,169 @@
{% include "references.md" %} {% include "references.md" %}
# Developers corner # Developers' corner
Python [AppImages][APPIMAGE] are built with the `python-appimage` utility, Python [AppImages][APPIMAGE] are created using the `python-appimage` utility,
available from [PyPI][PYPI]. This utility can also help packaging Python based which is available on [PyPI][PYPI]. This utility can also be used to package
applications as AppImages, using an existing Python AppImage and a recipe Python-based applications as AppImages using an existing AppImage and a recipe
folder. folder.
!!! Caution !!! Caution
The `python-appimage` utility can only package applications that can be The `python-appimage` utility can only package applications that can be
directly installed with `pip`. For more advanced usage, one needs to extract installed directly with `pip`. For more advanced usage, it is necessary to
the Python AppImage and to edit it, e.g. as explained in the [Advanced extract and edit the Python AppImage, as explained in the [Advanced
installation](index.md#advanced-installation) section. Additional details installation](index.md#advanced-installation) section. Further details on
on this use case are provided [below](#advanced-packaging). this use case can be found [below](#advanced-packaging).
## Building a Python AppImage ## Building a Python AppImage
The primary scope of `python-appimage` is to relocate an existing Python The primary purpose of `python-appimage` is to relocate an existing Python
installation inside an AppDir, and to build the corresponding AppImage. For installation to an AppDir and build the corresponding AppImage. For example, the
example, the following command
```bash ```bash
python-appimage build local -p $(which python2) python-appimage build local -p $(which python2)
``` ```
should build an AppImage of your local Python 2 installation, provided that it should create an AppImage of your local Python installation, provided that it
exists. exists.
!!! Tip !!! Tip
Help on available arguments and options to `python-appimage` can be obtained Help on the available arguments and options for `python-appimage` can be
with the `-h` flag. For example, `python-appimage build local -h` provides obtained by using the `-h` flag. For example, running
help on local builds. `python-appimage build local -h` provides help on local builds.
{{ begin(".capsule") }} {{ begin(".capsule") }}
### Auxiliary tools ### Auxiliary tools
The `python-appimage` utility relies on auxiliary tools that are downloaded and The `python-appimage` utility relies on auxiliary tools that are downloaded and
installed at runtime, on need. Those are [appimagetool][APPIMAGETOOL] for installed on demand during application execution. These are
building AppImages, and [patchelf][PATCHELF] in order to edit ELFs runtime paths [appimagetool][APPIMAGETOOL], which is used to build AppImages, and
(`RPATH`). Auxiliary tools are installed to the the user space. One can get [patchelf][PATCHELF], which is used to edit runtime paths (`RPATH`) in ELF
their location with the `which` command word. For example, files. These auxiliary tools are installed in the application cache. Their
location can be found using the `which` command. For example, the command
```bash ```bash
python-appimage which appimagetool python-appimage which appimagetool
``` ```
returns the location of `appimagetool`, if it has been installed. If not, the returns the location of [appimagetool][APPIMAGETOOL] if it has been installed.
`install` command word can be used in order to trigger its installation. If not, the `install` command can be used to trigger its installation.
{{ end(".capsule") }} {{ end(".capsule") }}
## Manylinux Python AppImages ## Manylinux Python AppImages
AppImages of your local `python` are unlikely to be portable, except if you run AppImages of your local `python` are unlikely to be portable, unless you are
an ancient Linux distribution. Indeed, a core component preventing portability running an outdated Linux distribution. A core component that prevents
across Linuses is the use of different versions of the `glibc` system library. portability across Linux distributions is the use of different versions of the
Hopefully, `glibc` is highly backward compatible. Therefore, a simple `glibc` system library. Fortunately, `glibc` is highly backward compatible.
work-around is to compile binaries using the oldest Linux distro you can afford Therefore, a simple workaround is to compile binaries using the oldest Linux
to. This is the strategy used for creating portable AppImages, as well as for distribution you can. This strategy is used to create portable AppImages and to
distributing Python site packages as ready-to-use binary [wheels][WHEELS]. distribute Python site packages as ready-to-use binary [wheels][WHEELS].
The Python Packaging Authority (PyPA) has defined standard platform tags for The Python Packaging Authority (PyPA) has defined standard platform tags for
building Python site packages, labelled [manylinux][MANYLINUX]. These build building Python site packages labelled [Manylinux][MANYLINUX]. These build
platforms are available as Docker images with various versions of Python already platforms are available as Docker images, with different versions of Python
installed. The `python-appimage` utility can be used to package those installs already installed. The `python-appimage` utility can be used to package these
as AppImages. For example, the following command installations as AppImages. For example, the following command
```bash ```bash
python-appimage build manylinux 2014_x86_64 cp310-cp310 python-appimage build manylinux 2014_x86_64 cp313-cp313
``` ```
should build an AppImage of Python 3.10 using the CPython (_cp310-cp310_) should build an AppImage of Python __3.13__ using the CPython (__cp313-cp313__)
install found in the `manylinux2014_x86_64` Docker image. installation found in the `manylinux2014_x86_64` Docker image.
!!! Note !!! Note
Docker needs to be already installed on your system in order to build From version `1.4.0` of `python-appimage` onwards, Docker is **no longer**
Manylinux Python images. However, the command above can be run on the host. required to build the Manylinux Python images. Cross-building is also
That is, you need **not** to explictly shell inside the manylinux Docker supported, for example producing an `aarch64` Python image from an `x86_64`
image. host.
!!! Warning
Creating multiple Manylinux Python images can significantly increase the
size of the application cache. This can be managed using the
`python-appimage cache` command.
!!! Tip !!! Tip
A compilation of ready-to-use Manylinux Python AppImages is available from A compilation of ready-to-use Manylinux Python AppImages is available in the
the [releases][RELEASES] area of the `python-appimage` [GitHub [releases][RELEASES] section of the `python-appimage` [GitHub
repository][GITHUB]. These AppImages are updated weekly, on every Sunday. repository][GITHUB]. These AppImages are updated weekly, on every Sunday.
!!! Tip
Instead of an AppImage, the `python-appimage build manylinux` command can
produce either an `AppDir` or a bare tarball (i.e. without the AppImage
layer) of a Manylinux Python installation. See the `-b` and `-n` command
line options for more information.
## Simple packaging ## Simple packaging
The `python-appimage` utility can also be used in order to build simple The `python-appimage` utility can also be used to package simple AppImage
applications, that can be `pip` installed. The syntax is applications, whose dependencies can be installed using `pip`. The syntax is
```bash ```bash
python-appimage build app -p 3.10 /path/to/recipe/folder python-appimage build app -p 3.13 /path/to/recipe/folder
``` ```
in order to build a Python 3.10 based application from a recipe folder. to build a Python 3.13-based application from a recipe folder. Examples of
Examples of recipes can be found on GitHub in the [applications][APPLICATIONS] recipes can be found in the [applications][APPLICATIONS] folder on GitHub. The
folder. The recipe folder contains: recipe folder contains
- the AppImage metadata (`application.xml` and `application.desktop`), - the AppImage metadata (`application.xml` and `application.desktop`),
- an application icon (e.g. `application.png`), - an application icon (e.g. `application.png`),
- a Python requirements file (`requirements.txt`) - a Python requirements file (`requirements.txt`),
- an entry point script (`entrypoint.sh`). - an entry point script (`entrypoint.sh`).
Additional information on metadata can be found in the AppImage documentation. Further information on metadata can be found in the AppImage documentation
That is, for [desktop][APPIMAGE_DESKTOP] and [AppStream XML][APPIMAGE_XML] (e.g., regarding [desktop][APPIMAGE_DESKTOP] and [AppStream XML][APPIMAGE_XML]
files. The `requirements.txt` file allows to specify additional site packages files). The `requirements.txt` file enables additional site packages to be
to be bundled in the AppImage, using `pip`. specified for bundling in the AppImage using `pip`.
!!! Caution !!! Caution
For the application to be portable, site packages bundled in the AppImage, In order for the application to be portable, the site packages bundled in
as well as their dependencies, must must be available as binary wheels, or the AppImage and their dependencies must be available as binary wheels or
be pure Python packages. pure Python packages.
If a **C extension** is bundled from **source**, then it will likely **not If a **C extension** is bundled from **source**, it will likely **not be
be portable**, as further discussed in the [Advanced portable**; this is discussed further in the [Advanced
packaging](#advanced-packaging) section. packaging](#advanced-packaging) section.
!!! Tip !!! Tip
Some site packages are available only for specific Manylinux tags. This can Some site packages are only available for specific Manylinux tags. You can
be cross-checked by browsing the `Download files` section on the package's check this by browsing the `Download files` section on the package's PyPI
PyPI page. page.
!!! Tip !!! Tip
Since version 1.2, `python-appimage` allows to specify local requirements as Since version 1.2, `python-appimage` allows local requirements to be
well, using the `local+` tag (see specified using the `local+` tag (see
[PR49](https://github.com/niess/python-appimage/pull/49)). Note however that [PR49](https://github.com/niess/python-appimage/pull/49)). Please note,
this performs a direct copy of the local package, which has several however, that this involves directly copying the local package, which has
limitations. several limitations.
{{ begin(".capsule") }} {{ begin(".capsule") }}
### Entry point script ### Entry point script
{% raw %} {% raw %}
The entry point script deserves some additional explanations. This script allows The entry point script deserves some additional explanations. This script lets
to customize the startup of your application. A typical `entrypoint.sh` script you customise your application's startup. A typical `entrypoint.sh` script would
would look like look like this
```bash ```bash
{{ python-executable }} ${APPDIR}/opt/python{{ python-version }}/bin/my_app.py "$@" {{ python-executable }} ${APPDIR}/opt/python{{ python-version }}/bin/my_app.py "$@"
``` ```
where `my_app.py` is the application startup script, installed by `pip`. As can where `my_app.py` is the application startup script installed by `pip`. As can
be seen from the previous example, the `entrypoint.sh` script recognises some be seen from the previous example, the `entrypoint.sh` script recognises
particular variables, nested between double curly braces, `{{ }}`. Those particular variables nested between double curly braces (`{{}}`). These
variables are listed in the table hereafter. In addition, usual [AppImage variables are listed in the table below. In addition, the usual [AppImage
environement variables][APPIMAGE_ENV] can be used as well, if needed. For environement variables][APPIMAGE_ENV] can be used if needed. For instance,
example, `$APPDIR` points to the AppImage mount point at runtime. `$APPDIR` points to the AppImage mount point at runtime.
{% endraw %} {% endraw %}
| variable | Description | | variable | Description |
|----------------------|---------------------------------------------------------------| |----------------------|---------------------------------------------------------------|
| `architecture` | The AppImage architecture, e.g. `x86_64`. | | `architecture` | The AppImage architecture, e.g. `x86_64`. |
@@ -173,20 +185,20 @@ example, `$APPDIR` points to the AppImage mount point at runtime.
{% raw %} {% raw %}
!!! Note !!! Note
By default, Python AppImages are not isolated from the user space, nor from By default, Python AppImages are not isolated from user space or
Python specific environment variables, the like `PYTHONPATH`. Depending on Python-specific environment variables such as `PYTHONPATH`. Depending on
your use case, this can be problematic. your use case, this can cause problems.
The runtime isolation level can be changed by adding the `-E`, `-s` or `-I` You can change the isolation level by adding the `-E`, `-s` or `-I` options
options, when invoking the runtime. For example, when invoking the runtime. For example, `{{ python-executable }} -I` starts
`{{ python-executable }} -I` starts a fully isolated Python instance. a fully isolated Python instance.
{% endraw %} {% endraw %}
### Bundling data files ### Bundling data files
`python-appimage` is also capable of bundling in auxilliary data files directly `python-appimage` is also capable of bundling auxiliary data files directly into
into the resulting AppImage. `-x/--extra-data` switch exists for that task. the resulting AppImage. The `-x/--extra-data` switch is used for this purpose.
Consider following example. Consider the following example.
```bash ```bash
echo -n "foo" > foo echo -n "foo" > foo
@@ -195,10 +207,10 @@ echo -n "baz" > bar/baz
python-appimage [your regular parameters] -x foo bar/* python-appimage [your regular parameters] -x foo bar/*
``` ```
User data included in such a way becomes accessible to the Python code In this way, user data becomes accessible to the Python code contained within
contained within the AppImage in a form of regular files under the directory the AppImage as regular files under the directory pointed to by the `APPDIR`
pointed to by `APPDIR` environment variable. Example of Python 3 script environment variable. An example of a Python 3 script that reads these files is
that reads these exemplary files is presented below. presented below.
```python ```python
import os, pathlib import os, pathlib
@@ -206,7 +218,7 @@ for fileName in ("foo", "baz"):
print((pathlib.Path(os.getenv("APPDIR")) / fileName).read_text()) print((pathlib.Path(os.getenv("APPDIR")) / fileName).read_text())
``` ```
Above code, when executed, would print following output. When executed, the above code would produce the following output.
```bash ```bash
foo foo
@@ -215,37 +227,36 @@ baz
## Advanced packaging ## Advanced packaging
In more complex cases, e.g. if your application relies on external C libraries In more complex cases, for example if your application relies on external C
not bundled with the Python runtime, then the simple packaging scheme described libraries that are not bundled with the Python runtime, the simple packaging
previously will fail. Indeed, this falls out of the scope of `python-appimage`, scheme described previously will not work. This falls outside the scope of
whose main purpose it to relocate an existing Python install. In this case, you `python-appimage`, which is primarily intended for relocating an existing Python
might rather refer to the initial AppImage [Packaging installation. In this case, you may wish to refer to the initial AppImage
Guide][APPIMAGE_PACKAGING], and use alternative tools like [Packaging Guide][APPIMAGE_PACKAGING], and use alternative tools such as
[linuxdeploy][LINUXDEPLOY]. [linuxdeploy][LINUXDEPLOY].
However, `python-appimage` can still be of use in more complex cases by However, `python-appimage` can still be useful in more complex cases, as it can
extracting its AppImages to an AppDir, as discussed in the [Advanced generate a base AppDir containing a relocatable Python runtime (e.g., using the
installation](index.md#advanced-installation) section. The extracted AppImages `-n` option). This can then serve as a starting point to create more complex
contain a relocatable Python runtime, that can be used as a starting base for AppImages.
building more complex AppImages.
!!! Tip !!! Tip
In some cases, a simple workaround to missing external libraries can be to In some cases, a simple workaround for missing external libraries is to
fetch portable versions of those from a Manylinux distro, and to bundle them download portable versions of them from a Manylinux distribution and bundle
under `AppDir/usr/lib`. You might also need to edit their dynamic section, them in `AppDir/usr/lib`. You may also need to edit the dynamic section
e.g. using [`patchelf`][PATCHELF], which is installed by `python-appimage`. using [`patchelf`][PATCHELF], which is installed by `python-appimage`.
{{ begin(".capsule") }} {{ begin(".capsule") }}
### C extension modules ### C extension modules
If your application relies on C extension modules, they need to be compiled on a If your application relies on C extension modules, these must be compiled on a
Manylinux distro in order to be portable. In addition, their dependencies need Manylinux distribution in order to be portable. Their dependencies also need to
to be bundled as well. In this case, you might better start by building a binary be bundled. In this case, it would be better to start by building a binary wheel
wheel of your package, using tools like [Auditwheel][AUDITWHEEL] which can of your package using tools like [Auditwheel][AUDITWHEEL], which can automate
automate some parts of the packaging process. Note that `auditwheel` is already some parts of the packaging process. Please note that `auditwheel` is already
installed on the Manylinux Docker images. installed on the Manylinux Docker images.
Once you have built a binary wheel of your package, it can be used with Once you have built a binary wheel of your package, you can use it with
`python-appimage` in order to package your application as an AppImage. `python-appimage` to package your application as an AppImage.
{{ end(".capsule") }} {{ end(".capsule") }}

167
docs/src/index.md
View File

@@ -15,8 +15,8 @@
# Python AppImages # Python AppImages
We provide relocatable Python runtimes for _Linux_ systems, as We provide relocatable Python runtimes for _Linux_ systems, as
[AppImages][APPIMAGE]. These runtimes have been extracted from [AppImages][APPIMAGE]. These runtimes have been extracted from a variety of
[manylinux][MANYLINUX] Docker images. [Manylinux][MANYLINUX] Docker images.
{{ "" | id("append-releases-list") }} {{ "" | id("append-releases-list") }}
## Basic installation ## Basic installation
@@ -35,23 +35,24 @@ chmod +x python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage
!!! Note !!! Note
As can be seen from the previous [example](#basic-installation-example), the As can be seen from the previous [example](#basic-installation-example), the
AppImage name contains several informations. That are, the Python full AppImage name contains several pieces of information. This includes the
version ({{ "3.10.2" | id("example-full-version") }}), the CPython tag Python full version ({{ "3.10.2" | id("example-full-version") }}), the
({{ "cp310-cp310" | id("example-python-tag") }}), the Linux compatibility [CPython tag][PEP_425] ({{ "cp310-cp310" | id("example-python-tag") }}), the
tag ({{ "manylinux2014" | id("example-linux-tag") }}) and the machine [Linux compatibility tag][MANYLINUX] ({{ "manylinux2014" |
architecture ({{ "x86_64" | id("example-arch-tag") }}). id("example-linux-tag") }}) and the machine architecture ({{ "x86_64" |
id("example-arch-tag") }}).
!!! Caution !!! Caution
One needs to **select an AppImage** that matches **system requirements**. A It is essential to **select an AppImage** that aligns with the **system's
summmary of available Python AppImages is provided at the specifications**. An overview of the available Python AppImages is provided
[bottom](#available-python-appimages) of this page. at the [bottom](#available-python-appimages) of this page.
{{ begin(".capsule") }} {{ begin(".capsule") }}
### Creating a symbolic link ### Creating a symbolic link
Since AppImages native names are rather lengthy, one might create a symbolic As AppImages' native names are quite lengthy, it might be relevant to create a
link, e.g. as symbolic link, for example as
{{ begin("#basic-installation-example-symlink") }} {{ begin("#basic-installation-example-symlink") }}
```bash ```bash
@@ -59,23 +60,23 @@ ln -s python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage python3.10
``` ```
{{ end("#basic-installation-example-symlink") }} {{ end("#basic-installation-example-symlink") }}
Then, executing the AppImage as Executing the AppImage as {{ "`./python3.10`" |
{{ "`./python3.10`" | id("basic-installation-example-execution") }} should id("basic-installation-example-execution") }} should then start a Python
start a Python interactive session on _almost_ any Linux, provided that **fuse** interactive session on almost any Linux distribution, provided that **fuse** is
is supported. supported.
{{ end(".capsule") }} {{ end(".capsule") }}
!!! Tip !!! Tip
Fuse is not supported on Windows Subsytem for Linux v1 (WSL1), preventing Fuse is not supported on Windows Subsystem for Linux v1 (WSL1), which
AppImages direct execution. Yet, one can still extract the content of Python prevents the direct execution of AppImages. However, it is still possible to
AppImages and use them, as explained in the [Advanced extract the contents of Python AppImages and use them, as explained in the
installation](#advanced-installation) section. [Advanced installation](#advanced-installation) section.
## Installing site packages ## Installing site packages
Site packages can be installed using `pip`, distributed with the AppImage. For Site packages can be installed using `pip`, which is distributed with Python
example, the following AppImages. For example, the following command
{{ begin("#site-packages-example") }} {{ begin("#site-packages-example") }}
```bash ```bash
@@ -83,23 +84,22 @@ example, the following
``` ```
{{ end("#site-packages-example") }} {{ end("#site-packages-example") }}
installs the numpy package, where it is assumed that a symlink to the AppImage installs the [numpy][NUMPY] package, assuming that a symlink to the AppImage has
has been previously created. When using the **basic installation** scheme, by been created beforehand. When using this **basic installation** scheme, Python
default Python packages are installed to your **user space**, i.e. under packages are installed by default to your **user space** (i.e. under `~/.local`
`~/.local` on Linux. on Linux).
!!! Note !!! Note
AppImage are read-only. Therefore, site packages cannot be directly AppImages are read-only. Therefore, site packages cannot be installed
installed to the AppImage. However, the AppImage can be extracted, as directly to the Python AppImage. However, the AppImage can be extracted, as
explained in the [Advanced installation](#advanced-installation) section. explained in the [Advanced installation](#advanced-installation) section.
{{ begin(".capsule") }} {{ begin(".capsule") }}
### Alternative site packages location ### Alternative site packages location
One can The `--target option` of pip can be used to specify an alternative installation
specify an alternative installation directory for site packages using the directory for site packages. For example, the following command
`--target` option of pip. For example, the following
{{ begin("#site-packages-example-target") }} {{ begin("#site-packages-example-target") }}
```bash ```bash
@@ -107,7 +107,9 @@ specify an alternative installation directory for site packages using the
``` ```
{{ end("#site-packages-example-target") }} {{ end("#site-packages-example-target") }}
installs the numpy package besides the AppImage, in a `packages` folder. installs the [numpy][NUMPY] package in the `packages` folder, besides the
AppImage.
{{ end(".capsule") }} {{ end(".capsule") }}
!!! Tip !!! Tip
@@ -116,33 +118,33 @@ installs the numpy package besides the AppImage, in a `packages` folder.
`PYTHONPATH` environment variable. `PYTHONPATH` environment variable.
!!! Caution !!! Caution
While Python AppImages are relocatable, site packages might not be. In Although Python AppImages are relocatable, site packages may not be. In
particular, packages installing executable Python scripts assume a fix particular, packages that install executable Python scripts assume a fixed
location of the Python runtime. If the Python AppImage is moved, then these location for the Python runtime. If the Python AppImage is moved, these
scripts will fail. This can be patched by editing the script scripts will fail. This can be resolved by either editing the script
[shebang][SHEBANG], or be reinstalling the corresponding package. [shebang][SHEBANG] or reinstalling the corresponding package.
## Isolating from the user environment ## Isolating from the user environment
By default, Python AppImages are not isolated from the user environment. For By default, Python AppImages are not isolated from the user environment. For
example, packages located under `~/.local/lib/pythonX.Y/site-packages` are example, packages located under `~/.local/lib/pythonX.Y/site-packages` are
loaded prior to AppImage's (system) ones. Note that this is the usual Python loaded before the AppImage's ones. Note that this is the standard Python runtime
runtime behaviour. However, it can be conflictual for some applications. behaviour. However, this can be conflictual for some applications.
In order to isolate your application from the user environment, the Python To isolate your application from the user environment, the Python runtime
runtime provides the `-E`, `-s` and `-I` options. For example, invoking a Python provides the `-E`, `-s` and `-I` options. For example, running {{ "`./python3.10
AppImage as {{ "`./python3.10 -s`" | id("user-isolation-example") }} prevents -s`" | id("user-isolation-example") }} prevents the loading of user site
the loading of user site packages (located under `~/.local`). Additionaly, the packages located under `~/.local`. Additionally, the `-E` option disables
`-E` option disables Python related environment variables. In particular, it Python-related environment variables. In particular, it prevents packages under
prevents packages under `PYTHONPATH` to be loaded. The `-I` option triggers both `PYTHONPATH` from being loaded. The `-I` option triggers both the `-E` and `-s`
`-E` and `-s`. options.
## Using a virtual environement ## Using a virtual environement
Isolation can also be achieved with a [virtual environment][VENV]. Python [Virtual environments][VENV] can also be used to achieve isolation. For example,
AppImages can create a `venv` using the standard syntax, e.g. as Python AppImages can create a `venv` using the standard syntax, as
{{ begin("#venv-example") }} {{ begin("#venv-example") }}
```bash ```bash
@@ -150,15 +152,16 @@ AppImages can create a `venv` using the standard syntax, e.g. as
``` ```
{{ end("#venv-example") }} {{ end("#venv-example") }}
Note that moving the base Python AppImage to another location breaks the virtual Please note that moving the base Python AppImage to a different location will
environment. This can be patched by editing symbolic links under `venv/bin`, as break the virtual environment. This can be resolved by editing the symbolic
well as the `home` variable in `venv/pyvenv.cfg`. The latter must point to the links in `venv/bin`, as well as the `home` variable in `venv/pyvenv.cfg`. The
AppImage directory. latter must point to the AppImage directory.
!!! Tip !!! Tip
Old Python AppImages, created before version 1.1, fail setting up `pip` Old Python AppImages created before version 1.1 fail to set up `pip`
automaticaly during `venv` creation. However, this can be patched by calling automatically during `venv` creation. However, this can be resolved by
`ensurepip` from within the `venv`, after its creation. For example, as calling `ensurepip` within the virtual environment after its creation. For
example, as
```bash ```bash
source /path/to/new/virtual/environment/bin/activate source /path/to/new/virtual/environment/bin/activate
@@ -170,10 +173,10 @@ python -m ensurepip
## Advanced installation ## Advanced installation
The [basic installation](#basic-installation) scheme described previously has The [basic installation](#basic-installation) scheme described previously has
some limitations when using Python AppImages as a runtime. For example, site certain limitations when Python AppImages are used as the runtime environment.
packages need to be installed to a separate location. This can be solved by For example, site packages need to be installed in a different location. This
extracting a Python AppImage to an `*.AppDir` directory, e.g. as issue can be resolved by extracting a Python AppImage to an `AppDir`
directory, e.g. as
{{ begin("#advanced-installation-example") }} {{ begin("#advanced-installation-example") }}
```bash ```bash
@@ -185,32 +188,32 @@ ln -s python3.10.2-cp310-cp310-manylinux2014_x86_64.AppDir/AppRun python3.10
``` ```
{{ end("#advanced-installation-example") }} {{ end("#advanced-installation-example") }}
Then, by default **site packages** are installed to the extracted **AppDir**, Then, by default, **site packages** are installed to the extracted `AppDir`
when using `pip`. In addition, executable scripts installed by `pip` are patched when using `pip`. Additionally, executable scripts installed by `pip` are
in order to use relative [shebangs][SHEBANG]. Consequently, the AppDir can be patched to use relative [shebangs][SHEBANG]. Consequently, the `AppDir` can be
freely moved around. moved around freely.
!!! Note !!! Note
Python AppDirs follow the [manylinux][MANYLINUX] installation scheme. Python `AppDirs` follow the [Manylinux][MANYLINUX] installation scheme.
Executable scripts are installed under `AppDir/opt/pythonX.Y/bin` where _X_ Executable scripts are installed under the `AppDir/opt/pythonX.Y/bin`
and _Y_ in _pythonX.Y_ stand for the major and minor version numbers. Site directory, where _X_ and _Y_ represent the major and minor version numbers,
packages are located under respectively. Site packages are located under
`AppDir/opt/pythonX.Y/lib/pythonX.Y/site-packages`. For convenience, `pip` `AppDir/opt/pythonX.Y/lib/pythonX.Y/site-packages`. For convenience,
installed applications are also mirrored under `AppDir/usr/bin`, using applications installed using `pip` are also mirrored under `AppDir/usr/bin`
symbolic links. using symbolic links.
!!! Tip !!! Tip
As for Python AppImages, by default the extracted runtime is [not isolated As for Python AppImages, the extracted runtime is [not isolated from the
from the user environment](#isolating-from-the-user-environment). This user environment](#isolating-from-the-user-environment) by default. This
behaviour can be changed by editing the `AppDir/usr/bin/pythonX.Y` wrapper behaviour can be changed by editing the `AppDir/usr/bin/pythonX.Y` wrapper
script, and by adding the `-s`, `-E` or `-I` option at the very bottom, script and adding the `-s`, `-E` or `-I` option to the line invoking Python
where Python is invoked. (at the end of the script).
{{ begin(".capsule") }} {{ begin(".capsule") }}
### Repackaging the AppImage ### Repackaging the AppImage
An extracted AppDir can be re-packaged as an AppImage using An extracted `AppDir` can be re-packaged as an AppImage using
[appimagetool][APPIMAGETOOL], e.g. as [appimagetool][APPIMAGETOOL], e.g. as
@@ -227,21 +230,21 @@ chmod +x appimagetool-x86_64.AppImage
``` ```
{{ end("#repackaging-example") }} {{ end("#repackaging-example") }}
This allows to customize your Python AppImage, for example by adding your This allows you to personalise your Python AppImage by adding your preferred
preferred site packages. site packages, for example.
{{ end(".capsule") }} {{ end(".capsule") }}
!!! Note !!! Note
Python AppImages can also be used for packaging Python based applications, Python AppImages can also be used to package Python-based applications as
as AppImages. Additional details are provided in the [developers AppImages. Further information can be found in the [developers'
section](apps). section](apps).
## Available Python AppImages ## Available Python AppImages
A summary of available Python AppImages [releases][RELEASES] is provided in the The [table](#appimages-download-links) below provides a summary of the available
[table](#appimages-download-links) below. Clicking on a badge should download Python AppImage [releases][RELEASES]. Clicking on a badge should download the
the corresponding AppImage. corresponding AppImage.
{{ begin("#suggest-appimage-download") }} {{ begin("#suggest-appimage-download") }}
!!! Caution !!! Caution

2
docs/src/js/index.js
View File

@@ -75,7 +75,7 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu
elements.push(`<a href="${release.url}">${release.version}</a>`) elements.push(`<a href="${release.url}">${release.version}</a>`)
} }
$("#append-releases-list").html( $("#append-releases-list").html(
" Available Python versions are " + " The available Python versions are " +
elements.slice(0, -1).join(", ") + elements.slice(0, -1).join(", ") +
" and " + " and " +
elements[elements.length - 1] + elements[elements.length - 1] +