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
We provide relocatable Python runtimes as [AppImages][APPIMAGE] for Linux
systems. These runtimes are extracted from [Manylinux][MANYLINUX] Docker images,
and they are available as GitHub [releases][RELEASES]. Our Python AppImages are
updated weekly, on every Sunday.
We provide relocatable Python runtimes in the form of [AppImages][APPIMAGE] for
Linux systems. These runtimes are extracted from [Manylinux][MANYLINUX] Docker
images and are available as GitHub [releases][RELEASES]. Our Python AppImages
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].
In addition, the online documentation describes the [`python-appimage`][PYPI]
utility, for application developers. This utility can facilitate the building of
Python apps, given an existing Python AppImage and a recipe folder.
[Examples][APPLICATIONS] of recipes are available from GitHub.
The online documentation also describes the [`python-appimage`][PYPI] utility
for application developers. This utility can facilitate the development of
Python applications, provided you have an existing Python AppImage and a recipe
folder. [Examples][APPLICATIONS] of recipes are available on GitHub.
## Projects using [`python-appimage`][GITHUB]

2
docs/include/references.md
View File

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

2
docs/mkdocs.yml
View File

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

231
docs/src/apps.md
View File

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

167
docs/src/index.md
View File

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