Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ This changelog summarizes major changes between GraalVM versions of the Python
language runtime. The main focus is on user-observable behavior of the engine.

## Version 25.1.0
* The standalone artifacts now include the Python version name before the Graal version. The new artifacts now start with `graalpy<PYTHON_VERSION>-<GRAAL_VERSION>-<OPERATING_SYSTEM>-<ARCHITECTURE>`.
* Standalone JVM artifacts are no longer released as separate distributions. For standalone deployments, use the GraalPy native artifacts. If you require Java interoperability, use a custom embedding.
* Treat foreign buffer objects as Python buffer-compatible binary objects, so APIs like `memoryview`, `bytes`, `bytearray`, `binascii.hexlify`, and `io.BytesIO` work naturally on them when embedding GraalPy in Java. This allows passing binary data between Python and Java's `ByteBuffer` and `ByteSequence` types with minimal (sometimes zero) copies.
* Add support for [Truffle source options](https://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/source/Source.SourceBuilder.html#option(java.lang.String,java.lang.String)):
* The `python.Optimize` option can be used to specify the optimization level, like the `-O` (level 1) and `-OO` (level 2) commandline options.
Expand All @@ -22,6 +24,7 @@ language runtime. The main focus is on user-observable behavior of the engine.
* Add an experimental `python.InitializationEntropySource` option to control the entropy source used for initialization-only randomness such as hash secret generation and `random.Random(None)` seeding. This means embeddings and tests can select deterministic or externally provided initialization entropy without affecting cryptographically relevant APIs like `os.urandom()` or `random.SystemRandom()`.
* Foreign temporal objects (dates, times, and timezones) are now given a Python class corresponding to their interop traits, i.e., `date`, `time`, `datetime`, or `tzinfo`. This allows any foreign objects with these traits to be used in place of the native Python types and Python methods available on these types work on the foreign types.
* Make BouncyCastle an optional dependency for embedding use cases. BouncyCastle is only needed for legacy RSA, DSA, and EC privat keys versions 0 and 1. To support these from Python embeddings, BouncyCastle must now be explicitly enabled by adding the `org.graalvm.python:python-bouncycastle-support` Maven artifact.
* The GraalPy Native standalone on Linux now uses a lower-footprint Native Image garbage collection configuration. This reduces resident set size (RSS) for many workloads, but may increase startup time and warmup time, and can slow down some workloads.

## Version 25.0.1
* Allow users to keep going on unsupported JDK/OS/ARCH combinations at their own risk by opting out of early failure using `-Dtruffle.UseFallbackRuntime=true`, `-Dpolyglot.engine.userResourceCache=/set/to/a/writeable/dir`, `-Dpolyglot.engine.allowUnsupportedPlatform=true`, and `-Dpolyglot.python.UnsupportedPlatformEmulates=[linux|macos|windows]` and `-Dorg.graalvm.python.resources.exclude=native.files`.
Expand All @@ -40,7 +43,6 @@ language runtime. The main focus is on user-observable behavior of the engine.
* Enable FTS3, FTS4, FTS5, RTREE, and math function features in the bundled sqlite3 library.
* Add support patches for Torch 2.7.0, PyGObject 3.52.3, xmlschema 4.0.0, lxml < 5.4.0, SciPy 1.15, jq 1.8.0, NumPy < 2.3, ormsgpack < 1.9.1, pandas 2.2.3, PyArrow 19.0, PyMuPDF 1.25.4.
* The GraalPy Native standalone on Linux now uses the G1 garbage collector which is much faster.
* The GraalPy Native standalone on Linux now uses a lower-footprint Native Image garbage collection configuration. This reduces resident set size (RSS) for many workloads, but may increase startup time and warmup time, and can slow down some workloads.
* The full-featured Python REPL is now available on GraalPy standalone builds for Windows.

## Version 24.2.0
Expand Down
2 changes: 1 addition & 1 deletion ci/graal/common.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"Jsonnet files should not include this file directly but use ci/common.jsonnet instead."
],

"mx_version": "7.79.1",
"mx_version": "7.81.0",

"COMMENT.jdks": "When adding or removing JDKs keep in sync with JDKs in ci/common.jsonnet",
"jdks": {
Expand Down
49 changes: 8 additions & 41 deletions docs/site/01-python-developers.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,8 +74,8 @@ audience_identifier: python
<h3 class="langstarter__title">Install or Download</h3>
<div>
<h5 class="download-text">
GraalPy is available for multiple platforms in two variants: <strong class="language-downloads__variant-native">Native</strong> (for a compact download size and smaller footprint) and <strong class="language-downloads__variant-jvm">JVM</strong> (for full Java interoperability). Distributions based on Oracle GraalVM provide the best performance and advanced features and are released under the <a href="https://www.oracle.com/downloads/licenses/graal-free-license.html">GFTC license</a>. Distributions based on GraalVM Community Edition, released under the OSI-approved <a href="https://opensource.org/licenses/UPL">UPL license</a>, are available on <a href="https://github.com/oracle/graalpython/releases">GitHub</a>.
See <a href="/python/python-developers/docs/#choosing-a-graalpy-distribution">Choosing a GraalPy Distribution</a> for guidance on selecting the appropriate runtime.
GraalPy is available for multiple platforms. Distributions based on Oracle GraalVM provide the best performance and advanced features and are released under the <a href="https://www.oracle.com/downloads/licenses/graal-free-license.html">GFTC license</a>. Distributions based on GraalVM Community Edition, released under the OSI-approved <a href="https://opensource.org/licenses/UPL">UPL license</a>, are available on <a href="https://github.com/oracle/graalpython/releases">GitHub</a>.
See <a href="/python/python-developers/docs/#choosing-a-graalpy-distribution">Choosing a GraalPy Distribution</a> for guidance on available distributions.
</h5>
</div>
<div class="languages__example-card">
Expand Down Expand Up @@ -160,48 +160,30 @@ docker run --rm ghcr.io/graalvm/graalpy-community:{{ site.language_version }} py
<table class="centered">
<tr>
<th class="border-correct-3">Version</th>
<th>Kind</th>
<th>Linux (aarch64)</th>
<th>Linux (amd64)</th>
<th>macOS (aarch64)</th>
<th class="border-correct-4">Windows (amd64)</th>
</tr>
<tr>
<td rowspan="2">
<td>
{{ site.language_version }}
</td>
<td>Native</td>
<td><a target="_blank" href="https://github.com/oracle/graalpython/releases/download/graal-{{ site.language_version }}/graalpy-{{ site.language_version }}-linux-aarch64.tar.gz">
<td><a target="_blank" href="https://github.com/oracle/graalpython/releases/download/graal-{{ site.language_version }}/graalpy{{ site.python_version }}-{{ site.language_version }}-linux-aarch64.tar.gz">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
<td><a target="_blank" href="https://github.com/oracle/graalpython/releases/download/graal-{{ site.language_version }}/graalpy-{{ site.language_version }}-linux-amd64.tar.gz">
<td><a target="_blank" href="https://github.com/oracle/graalpython/releases/download/graal-{{ site.language_version }}/graalpy{{ site.python_version }}-{{ site.language_version }}-linux-amd64.tar.gz">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
<td><a target="_blank" href="https://github.com/oracle/graalpython/releases/download/graal-{{ site.language_version }}/graalpy-{{ site.language_version }}-macos-aarch64.tar.gz">
<td><a target="_blank" href="https://github.com/oracle/graalpython/releases/download/graal-{{ site.language_version }}/graalpy{{ site.python_version }}-{{ site.language_version }}-macos-aarch64.tar.gz">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
<td><a target="_blank" href="https://github.com/oracle/graalpython/releases/download/graal-{{ site.language_version }}/graalpy-{{ site.language_version }}-windows-amd64.tar.gz">
<td><a target="_blank" href="https://github.com/oracle/graalpython/releases/download/graal-{{ site.language_version }}/graalpy{{ site.python_version }}-{{ site.language_version }}-windows-amd64.zip">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
</tr>
<tr>
<td>JVM</td>
<td><a target="_blank" href="https://github.com/oracle/graalpython/releases/download/graal-{{ site.language_version }}/graalpy-jvm-{{ site.language_version }}-linux-aarch64.tar.gz">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
<td><a target="_blank" href="https://github.com/oracle/graalpython/releases/download/graal-{{ site.language_version }}/graalpy-jvm-{{ site.language_version }}-linux-amd64.tar.gz">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
<td><a target="_blank" href="https://github.com/oracle/graalpython/releases/download/graal-{{ site.language_version }}/graalpy-jvm-{{ site.language_version }}-macos-aarch64.tar.gz">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
<td><a target="_blank" href="https://github.com/oracle/graalpython/releases/download/graal-{{ site.language_version }}/graalpy-jvm-{{ site.language_version }}-windows-amd64.tar.gz">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
</tr>
<tr>
<td class="border-correct-1" rowspan="2">Latest early access build</td>
<td>Native</td>
<td class="border-correct-1">Latest early access build</td>
<td><a target="_blank" href="https://raw.githubusercontent.com/graalvm/graal-languages-ea-builds/refs/heads/main/graalpy/versions/latest-native-linux-aarch64.url" onclick="resolveEarlyAccessDownload(event, this.href)">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
Expand All @@ -215,21 +197,6 @@ docker run --rm ghcr.io/graalvm/graalpy-community:{{ site.language_version }} py
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
</tr>
<tr>
<td>JVM</td>
<td><a target="_blank" href="https://raw.githubusercontent.com/graalvm/graal-languages-ea-builds/refs/heads/main/graalpy/versions/latest-jvm-linux-aarch64.url" onclick="resolveEarlyAccessDownload(event, this.href)">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
<td><a target="_blank" href="https://raw.githubusercontent.com/graalvm/graal-languages-ea-builds/refs/heads/main/graalpy/versions/latest-jvm-linux-amd64.url" onclick="resolveEarlyAccessDownload(event, this.href)">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
<td><a target="_blank" href="https://raw.githubusercontent.com/graalvm/graal-languages-ea-builds/refs/heads/main/graalpy/versions/latest-jvm-darwin-aarch64.url" onclick="resolveEarlyAccessDownload(event, this.href)">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
<td class="border-correct-2"><a target="_blank" href="https://raw.githubusercontent.com/graalvm/graal-languages-ea-builds/refs/heads/main/graalpy/versions/latest-jvm-windows-amd64.url" onclick="resolveEarlyAccessDownload(event, this.href)">
<img src="{{ '/assets/img/download-icon.svg' | relative_url }}" class="" alt="download icon">
</a></td>
</tr>
</table>
</div>
<div class="example-logo-box">
Expand Down
1 change: 1 addition & 0 deletions docs/site/_config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ baseurl: "/python"
url: "https://graalvm.org"
github: "oracle/graalpython"
language_version: 25.0.2
python_version: 3.12
name: GraalPy
permalink: pretty

Expand Down
4 changes: 2 additions & 2 deletions docs/user/Python-on-JVM.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ This guide shows you how to migrate from Jython to GraalPy.

### Prerequisites

- To move plain Jython scripts from Jython to GraalPy, use a GraalPy JVM-based runtime. (For more information, see available [GraalPy Distributions](Python-Runtime.md))
- First migrate code from Python 2 to Python 3 following [the official guide from the Python community](https://docs.python.org/3/howto/pyporting.html)
- To migrate Jython scripts to GraalPy, you first need to create a GraalPy embedding. For more information, see [Embedding Python in Java](Embedding-Getting-Started.md).
- Make sure to migrate code from Python 2 (as supported by Jython) to Python 3 (the major version GraalPy is compatible with) following [the official guide from the Python community](https://docs.python.org/3/howto/pyporting.html)

## GraalPy Java Interoperability Overview

Expand Down
53 changes: 18 additions & 35 deletions docs/user/Standalone-Getting-Started.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,37 +12,20 @@ GraalPy is available in multiple distributions:
- **GraalPy built on Oracle GraalVM** provides the best experience with additional optimizations, significantly faster performance, and better memory efficiency. It is licensed under the [GraalVM Free Terms and Conditions (GFTC)](https://www.oracle.com/downloads/licenses/graal-free-license.html), which permits use by any user including commercial and production use. Redistribution is permitted as long as it is not for a fee.
- **GraalPy Community** is built on top of GraalVM Community Edition and is fully open source.

### Runtime Options
### Runtime

Two language runtime options are available for both distributions:

- **Native** (recommended for standalone use)
- GraalPy is compiled ahead-of-time to a native executable
- You do not need a JVM to run GraalPy and it is compact in size
- Faster startup time
- Faster time to reach peak performance
- **JVM**
- You can easily exploit Java interoperability
- Peak performance may be higher than the native option
- Slower startup time
The standalone GraalPy runtime is compiled ahead-of-time to a native executable.
You do not need a JVM to run it, and it has a compact size, fast startup, and fast time to reach peak performance.
For Java interoperability and JVM application embedding, see [Embedding Python in Java](Embedding-Getting-Started.md).

### Distribution Identification

The GraalPy runtimes are identified using the pattern _graalpy(-community)(-jvm)-&lt;version&gt;-&lt;os&gt;-&lt;arch&gt;_:

| Distribution | Native | JVM |
| ------------- | ----------------------------------------- | ---- |
| **Oracle** | `graalpy-<version>-<os>-<arch>` | `graalpy-jvm-<version>-<os>-<arch>` |
| **Community** | `graalpy-community-<version>-<os>-<arch>` | `graalpy-community-jvm-<version>-<os>-<arch>` |

### Runtime Comparison
The GraalPy standalone runtimes are identified using the pattern _graalpy(-community)&lt;python-version&gt;-&lt;graal-version&gt;-&lt;os&gt;-&lt;arch&gt;_:

| Runtime | Native (default) | JVM |
|:-------|:-----------------|:----|
| Time to start | faster | slower |
| Time to reach peak performance | faster | slower |
| Peak performance (also considering GC) | good | best |
| Java interoperability | needs configuration | works |
| Distribution | Runtime | License |
|---------------|-----------------------------------------------------------------|---------------------------------------------------------------------------|
| **Oracle** | `graalpy<python-version>-<graal-version>-<os>-<arch>` | [GFTC](https://www.oracle.com/downloads/licenses/graal-free-license.html) |
| **Community** | `graalpy-community<python-version>-<graal-version>-<os>-<arch>` | [UPL](https://opensource.org/licenses/UPL) |

## GraalPy Capabilities

Expand Down Expand Up @@ -78,14 +61,14 @@ pyenv shell graalpy-25.0.2

1. Download the appropriate binary from [GitHub releases](https://github.com/oracle/graalpython/releases):

- AMD64: `graalpy-XX.Y.Z-linux-amd64.tar.gz`
- ARM64: `graalpy-XX.Y.Z-linux-aarch64.tar.gz`
- AMD64: `graalpy3.12-25.1.0-linux-amd64.tar.gz`
- ARM64: `graalpy3.12-25.1.0-linux-aarch64.tar.gz`

2. Extract and add it to your `PATH` environment variable:

```bash
tar -xzf graalpy-25.0.2-linux-amd64.tar.gz
export PATH="$PWD/graalpy-25.0.2-linux-amd64/bin:$PATH"
tar -xzf graalpy3.12-25.1.0-linux-amd64.tar.gz
export PATH="$PWD/graalpy3.12-25.1.0-linux-amd64/bin:$PATH"
```

### macOS
Expand Down Expand Up @@ -115,8 +98,8 @@ pyenv shell graalpy-25.0.2
3. Extract and add it to your `PATH` environment variable:

```bash
tar -xzf graalpy-25.0.2-macos-aarch64.tar.gz
export PATH="$PWD/graalpy-25.0.2-macos-aarch64/bin:$PATH"
tar -xzf graalpy3.12-25.1.0-macos-aarch64.tar.gz
export PATH="$PWD/graalpy3.12-25.1.0-macos-aarch64/bin:$PATH"
```

### Windows
Expand All @@ -129,9 +112,9 @@ pyenv shell graalpy-25.0.2

```powershell
# Extract the file and update your PATH environment variable
# to include the graalpy-XX.Y.Z-windows-amd64/bin directory
tar -xzf graalpy-25.0.2-windows-amd64.tar.gz
$env:PATH = "$PWD\graalpy-25.0.2-windows-amd64\bin;$env:PATH"
# to include the graalpy3.12-25.1.0-windows-amd64/bin directory
tar -xzf graalpy3.12-25.1.0-windows-amd64.zip
$env:PATH = "$PWD\graalpy3.12-25.1.0-windows-amd64\bin;$env:PATH"
```

#### Known Windows Limitations
Expand Down
7 changes: 4 additions & 3 deletions mx.graalpython/suite.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
# METADATA
#
# --------------------------------------------------------------------------------------------------------------
"mxversion": "7.67.0",
"mxversion": "7.81.0",
"name": "graalpython",
"versionConflictResolution": "latest",

Expand Down Expand Up @@ -1715,13 +1715,14 @@
"class": "DeliverableStandaloneArchive",
"platformDependent": True,
"standalone_dist": "GRAALPY_NATIVE_STANDALONE",
"community_archive_name": "graalpy-community",
"enterprise_archive_name": "graalpy",
"community_archive_name": "graalpy-community<py_ver:major_minor>",
"enterprise_archive_name": "graalpy<py_ver:major_minor>",
"language_id": "python",
},

"GRAALPY_JVM_STANDALONE_RELEASE_ARCHIVE": {
"class": "DeliverableStandaloneArchive",
"deploy": False,
"platformDependent": True,
"standalone_dist": "GRAALPY_JVM_STANDALONE",
"community_archive_name": "graalpy-community-jvm",
Expand Down
Loading
Loading