Skip to content

Commit 790d89a

Browse files
ban-miban-mi
committed
Tech writer run through
1 parent 2314319 commit 790d89a

File tree

2 files changed

+86
-56
lines changed

2 files changed

+86
-56
lines changed

‎docs/site/_config.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
baseurl: "/python"
22
url: "https://graalvm.org"
33
github: "oracle/graalpython"
4-
language_version: 25.0.0
4+
language_version: 25.0.1
55
name: GraalPy
66

77
permalink: pretty

‎docs/user/Native-Images-with-Python.md‎

Lines changed: 85 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,118 @@
11
# Native Executables with Python
22

3-
GraalPy supports GraalVM Native Image to generate native binaries of Java applications that use GraalPy.
3+
GraalPy supports GraalVM Native Image to generate native binaries of Java applications that embed Python code.
44

55
## Quickstart
66

7-
If you started with the [Maven archetype](README.md), the generated _pom.xml_ makes it easy to generate a native executable using the [Maven plugin for Native Image building](https://graalvm.github.io/native-build-tools/latest/maven-plugin.html).
7+
If you started with the [Maven archetype](README.md), the generated _pom.xml_ file already includes the necessary configuration for creating a native executable using the [Maven plugin for Native Image building](https://graalvm.github.io/native-build-tools/latest/maven-plugin.html).
88

99
To build the application, run:
10+
1011
```bash
1112
mvn -Pnative package
1213
```
13-
The command packages the project and creates a native executable.
1414

15-
Take a look at the generated files _pom.xml_ and _Main.java_.
16-
They are documented to explain how Python resources are included in the resulting binary.
17-
The generated project should be viewed as a starting point.
18-
It includes the entire Python standard library, so the Python code can invoke all of the standard library code.
19-
The resources can be manually pruned to reduce the included Python libraries to the necessary amount, reducing both the size of the package and the time to start up.
20-
This Java example demonstrates some useful default options for the Python context, but other settings may be desirable to further control what the Python code is allowed to do.
15+
This command packages the project and creates a native executable.
16+
17+
The generated _pom.xml_ and _Main.java_ files explain how Python resources are included in the resulting binary.
18+
The generated project serves as a starting point and includes the entire Python standard library by default, allowing your Python code to use any standard library modules.
19+
You can manually remove unused Python libraries to reduce both the executable size and startup time.
20+
The created example demonstrates useful default options for the Python context, but you can adjust these settings to control what your Python code can access.
2121

2222
## Reducing Binary Size
2323

24-
Python is a large language.
25-
"Batteries included" has long been a core tenet of CPython.
26-
As a compatible replacement, GraalPy includes most of those "batteries" as well.
27-
This can result in significant increases in binary size when including GraalPy in a Java application.
28-
29-
Only you as the developer know your specific embedding scenario.
30-
The defaults may include much more than needed for any specific application.
31-
An embedded Python-in-Java application usually has more limited use cases for the Python interpreter than the full GraalPy distribution, and often you can know ahead of time whether certain features are needed.
32-
Some features (for example, cryptographic algorithms or socket access) may even be undesirable to include in some cases.
33-
Thus, when embedding GraalPy in a Java application, the binary size can be reduced and security improved by excluding components of the Python language.
34-
35-
### Excluding Python Components
36-
37-
GraalPy defines a few system properties that can be passed on the `native-image` command line to exclude aspects of the language.
38-
The options can, when taken together, reduce the size of the executable by around 20%.
39-
These are:
40-
41-
* `python.WithoutSSL=true` - This option removes the `ssl` module.
42-
If no secure network access or certificate checking is required, this removes Java's SSL classes and the BouncyCastle library.
43-
* `python.WithoutDigest=true` - This option removes the `_md5`, `_sha1`, `_sha256`, `_sha512`, `_sha3`, and `_hashlib` modules.
44-
This removes the direct usages of `java.security.MessageDigest` and `javax.crypto.Mac` from GraalPy.
45-
* `python.WithoutPlatformAccess=true` - This removes the `signal` and `subprocess` modules, removes accesses to process properties such as the Unix UID and GID, or setting the Java default time zone.
46-
This has no significant impact on binary size, but if these are unwanted capabilities that are dynamically disabled with context options anyway, they can also be removed ahead of time.
47-
* `python.WithoutCompressionLibraries=true` - This removes the `zlib`, `lzma`, `bzip2`, and `zipimporter` modules and related classes.
48-
These modules have both native and pure Java implementations (the former for performance, the latter for better sandboxing); however, if they are not needed, they can be removed entirely.
49-
* `python.WithoutNativePosix=true` - The default `os` module backend is a pure Java implementation when GraalPy is embedded rather than run via its launcher.
50-
The native POSIX backend of GraalPy is recommended only for 100% compatibility with CPython's POSIX interfaces, and if not used, can be removed from the build with this option.
51-
* `python.WithoutJavaInet=true` - The Java implementation of Python's `socket` module is based on Java's networking classes.
52-
If network access is denied for an embedding scenario, this option can reduce the binary size further.
53-
* `python.AutomaticAsyncActions=false` - Signal handling, Python weak reference callbacks, and cleaning up native resources is usually achieved automatically by spawning GraalPy daemon threads that submit safepoint actions to the Python main thread.
54-
This uses an `ExecutorService` with a thread pool.
55-
If you want to disallow such extra threads or avoid pulling in `ExecutorService` and related classes, then set this property to `false` and retrieve the `PollPythonAsyncActions` object from the context's polyglot bindings.
56-
This object is executable and can be used to trigger Python asynchronous actions at the locations you desire.
57-
58-
59-
### Removing Pre-initialized Python Heap
60-
61-
Another useful option to reduce the size of the native executable is to omit a pre-initialized Python context from the executable.
62-
By default, a default Python context is already pre-initialized and ready for immediate execution.
63-
This can lead to slightly improved startup, at the cost of including a few thousand Python objects in the binary.
64-
In embedded applications that use a custom polyglot engine to allow context sharing, the pre-initialized context cannot be used at all, and including those objects is wasted.
65-
The pre-initialized heap can be omitted by passing the following to the `native-image` command:
24+
Python is a feature-rich language with an extensive standard library.
25+
CPython's philosophy of "batteries included" means it ships with many built-in modules and libraries.
26+
As a compatible Python implementation, GraalPy includes most of these same "batteries."
27+
However, this can result in large native executables when embedding GraalPy in Java applications.
28+
You can significantly reduce the size by excluding components your application doesn't need by considering what your Python code actually uses.
29+
30+
### Available Optimizations
31+
32+
GraalPy provides several system properties that exclude specific language components.
33+
When used together, these can reduce executable size by approximately 20%.
34+
35+
| Property | Removes | Size Impact | Use Case |
36+
| ----------------------------------------- | ------------------------------------------------------------ | ----------- | ------------------------------------- |
37+
| `python.WithoutSSL=true` | SSL/TLS support (`ssl` module) | **High** | No HTTPS or certificates needed |
38+
| `python.WithoutDigest=true` | Crypto hash modules (`_md5`, `_sha1`, `_sha256`, etc.) | **Medium** | No cryptographic hashing required |
39+
| `python.WithoutCompressionLibraries=true` | Compression modules (`zlib`, `lzma`, `bzip2`, `zipimporter`) | **Medium** | No compression/decompression needed |
40+
| `python.WithoutJavaInet=true` | Network socket support (`socket` module) | **Medium** | No network access required |
41+
| `python.WithoutNativePosix=true` | Native POSIX API backend | **Low** | Embedded Java-only scenarios |
42+
| `python.WithoutPlatformAccess=true` | System process access (`signal`, `subprocess`) | **Low** | Security-focused deployments |
43+
| `python.AutomaticAsyncActions=false` | Automatic async thread management | **Low** | Manual async action control |
44+
45+
## Build Configuration Examples
46+
47+
### Maven Configuration
48+
49+
To apply size optimizations in Maven, configure these build arguments to your _pom.xml_ file within the native plugin configuration:
50+
51+
```xml
52+
<plugin>
53+
<groupId>org.graalvm.buildtools</groupId>
54+
<artifactId>native-maven-plugin</artifactId>
55+
<version>0.9.28</version>
56+
<configuration>
57+
<buildArgs>
58+
<!-- Remove unused Python components for smaller size -->
59+
<buildArg>-Dpython.WithoutSSL=true</buildArg>
60+
<buildArg>-Dpython.WithoutDigest=true</buildArg>
61+
<buildArg>-Dpython.WithoutCompressionLibraries=true</buildArg>
62+
<buildArg>-Dpython.WithoutJavaInet=true</buildArg>
63+
<buildArg>-Dpython.WithoutNativePosix=true</buildArg>
64+
<buildArg>-Dpython.WithoutPlatformAccess=true</buildArg>
65+
<buildArg>-Dpython.AutomaticAsyncActions=false</buildArg>
66+
67+
<!-- Remove pre-initialized Python context -->
68+
<buildArg>-Dimage-build-time.PreinitializeContexts=</buildArg>
69+
70+
<!-- Increase memory for the build process -->
71+
<buildArg>-J-Xmx8g</buildArg>
72+
</buildArgs>
73+
</configuration>
74+
</plugin>
75+
```
76+
77+
> Note: Remove any `'-Dpython.WithoutX=true'` entries for components your application needs.
78+
79+
## Removing Pre-initialized Python Heap
80+
81+
By default, GraalPy includes a pre-initialized Python context in the executable for faster startup.
82+
However, this adds several thousand Python objects to your binary.
83+
You should remove this if:
84+
- Creating more than one context
85+
- Binary size is more important than a slight startup delay
86+
87+
To remove the pre-initialized heap, add this flag to your build configuration:
6688

6789
```bash
6890
-Dimage-build-time.PreinitializeContexts=
6991
```
7092

7193
### Disabling Runtime Compilation of Python Code
7294

73-
If binary size is significantly more important than execution speed (which may be the case if all Python scripts are expected to be short running, perform a lot of I/O, or scripts are rarely executed more than once), it may make sense to disable JIT compilation entirely.
95+
If binary size is significantly more important than execution speed, you can disable JIT compilation entirely.
96+
97+
You should use this if:
98+
99+
- Your Python scripts are very short-running
100+
- Performance is not critical
101+
- Your scripts spend most time on I/O operations
102+
74103
Be aware that this may significantly impact your Python performance, so be sure to test the runtime behavior of your actual use cases when choosing to use this option.
104+
75105
This can be achieved by passing the following options:
76106

77107
```bash
78-
-Dtruffle.TruffleRuntime=com.oracle.truffle.api.impl.DefaultTruffleRuntime \
108+
-Dtruffle.TruffleRuntime=com.oracle.truffle.api.impl.DefaultTruffleRuntime
79109
-Dpolyglot.engine.WarnInterpreterOnly=false
80110
```
81111

82112
### Summary
83113

84-
Combining all of these approaches can halve the size of the GraalPy binary.
85-
Every embedded application is different and the code pulled in by the rest of the Java code also matters, so combinations of these options should be tried to determine which effect they have in a specific instance.
114+
Combining these approaches can reduce the binary size by 50% or more.
115+
Since every application is different, experiment with different combinations to find what works best for your specific use case.
86116

87117
## Shipping Python Packages
88118

0 commit comments

Comments
 (0)