This document describes how the g4f project is packaged and distributed to end users through multiple channels: PyPI (Python Package Index), platform-specific executables, Docker images, and system package managers. The automated build and release pipeline is implemented in GitHub Actions workflows that handle multi-platform compilation, artifact generation, and publication.
For information about deploying these packages, see Docker Deployment and Environment Configuration. For details on the build and release pipeline automation, see Build & Release Pipeline.
The g4f project provides five primary distribution channels, each targeting different user preferences and deployment scenarios:
| Distribution Channel | Format | Platforms | Use Case |
|---|---|---|---|
| PyPI | Python wheel + source tarball | All platforms with Python | Developers, integration into Python projects |
| Executables | Standalone binaries (Nuitka) | Windows, Linux (x64/ARM64), macOS (x64/ARM64) | End users without Python installed |
| Docker | Container images | linux/amd64, linux/arm64, linux/arm/v7 | Server deployments, containerized environments |
| WinGet | Package manifest | Windows | Windows users via winget install |
| GitHub Releases | All artifacts | All platforms | Direct download of any format |
Sources: .github/workflows/build-packages.yml1-471
Distribution Pipeline Flow
The build pipeline is triggered by pushing a git tag or manual workflow dispatch. The prepare job determines the version string from the git tag reference or manual input, then outputs this version to all downstream jobs. Five parallel build jobs compile artifacts for different platforms, and a final create-release job aggregates all artifacts into a GitHub release.
Sources: .github/workflows/build-packages.yml3-13 .github/workflows/build-packages.yml15-37
Version Determination Logic
The version string is determined by the prepare job in .github/workflows/build-packages.yml22-36 The logic prioritizes git tag names for release builds, falls back to manual input for testing, and defaults to 0.0.0-dev for development builds. The is_release boolean flag controls whether Docker images are published and whether a GitHub release is created.
Sources: .github/workflows/build-packages.yml15-37
The PyPI build job creates both a wheel (.whl) and source distribution (.tar.gz) using Python's standard build module:
PyPI Build Job Steps
The PyPI distribution is built using the standard Python packaging toolchain. The G4F_VERSION environment variable is set from the prepare job output and used by the build system to version the package correctly.
The build produces:
.whl): Binary distribution for fast installation.tar.gz): Source code distribution for compatibilityPackage verification is performed using twine check to ensure metadata compliance before artifact upload.
Sources: .github/workflows/build-packages.yml40-65
The commented-out PyPI publishing job at .github/workflows/build-packages.yml474-490 shows the infrastructure for automatic PyPI uploads using trusted publishing (OIDC), though this is currently disabled in favor of manual publishing.
A separate, simpler PyPI publishing workflow exists at .github/workflows/publish-to-pypi.yml1-51 that publishes directly on tag pushes without building executables.
Standalone executables are compiled using Nuitka, a Python-to-binary compiler that bundles the Python interpreter and all dependencies into a single executable file.
The executable builds use GitHub Actions matrix strategy to target multiple platforms and architectures:
| Platform | Architectures | Runner | Job Name |
|---|---|---|---|
| Windows | x64 | windows-latest | build-windows-exe |
| Linux | x64, ARM64 | ubuntu-latest, ubuntu-24.04-arm | build-linux-exe |
| macOS | x64, ARM64 | macos-latest | build-macos-exe |
Sources: .github/workflows/build-packages.yml68-130 .github/workflows/build-packages.yml131-184 .github/workflows/build-packages.yml186-237
Nuitka Build Steps
Each platform follows the same build pattern:
requirements.txtg4f_cli.py script is generated that:
g4f.debug.version_check = Falseg4f.debug.version = "${{ version }}"g4f.cli.main()scripts/build-nuitka.sh script invokes Nuitka with platform-specific flagsSources: .github/workflows/build-packages.yml84-115 .github/workflows/build-packages.yml150-179 .github/workflows/build-packages.yml203-232
The entry point script example for Windows (.github/workflows/build-packages.yml90-106):
Windows: Executables are compressed into ZIP archives for easier distribution and to work around path length limitations:
Linux: Supports both x86_64 and ARM64 architectures using different GitHub-hosted runners:
ubuntu-latest (x86_64)ubuntu-24.04-arm (aarch64)macOS: Uses a single macos-latest runner but builds both x64 and ARM64 variants through cross-compilation:
Docker images are built only for release tags (is_release == 'true') and published to Docker Hub under hlohaus789/g4f.
Three image variants are built with different optimization profiles:
| Variant | Platforms | Dockerfile | Use Case |
|---|---|---|---|
| Full | linux/amd64 | docker/Dockerfile | Complete features including browser automation with noVNC |
| Slim | linux/amd64, linux/arm64 | docker/Dockerfile-slim | Minimal dependencies, smaller image size |
| ARM v7 | linux/arm/v7 | docker/Dockerfile-armv7 | Raspberry Pi and other ARM v7 devices |
Sources: .github/workflows/build-packages.yml239-298
Docker Build and Push Process
The Docker build job uses Docker Buildx with QEMU emulation to cross-compile images for multiple architectures from a single AMD64 runner. Each image variant is tagged with both latest-{variant} and {version}-{variant} tags for flexible versioning.
The G4F_VERSION build argument is passed to all Docker builds (.github/workflows/build-packages.yml273-274 .github/workflows/build-packages.yml286-287 .github/workflows/build-packages.yml297-298) to embed the version string in the container.
Sources: .github/workflows/build-packages.yml239-298
Windows Package Manager (WinGet) manifests are automatically generated for releases, enabling Windows users to install g4f via winget install gpt4free.
WinGet Manifest Creation
The create-winget-manifest job depends on build-windows-exe completion and only runs for release builds. It generates three YAML files conforming to the WinGet manifest schema v1.4.0:
g4f.yaml): Basic package metadata and versiong4f.installer.yaml): Download URL, hash, and installer typeg4f.locale.en-US.yaml): Human-readable descriptions and licensingThe installer manifest uses a nested portable installer configuration (.github/workflows/build-packages.yml369-380):
This configuration instructs WinGet to:
g4f in the user's PATHSources: .github/workflows/build-packages.yml334-409
The final step of the build pipeline aggregates all artifacts into a comprehensive GitHub release with download links and installation instructions.
Release Creation Workflow
The create-release job has dependencies on all build jobs (.github/workflows/build-packages.yml414) and only runs for release builds. It downloads all uploaded artifacts and attaches them to a new GitHub release.
The release body is auto-generated with structured installation instructions (.github/workflows/build-packages.yml434-458):
The release also includes a notice directing users to an alternative Windows launcher project for users experiencing issues with the Nuitka-compiled executable.
Sources: .github/workflows/build-packages.yml411-471
All build artifacts are attached to the release using glob patterns (.github/workflows/build-packages.yml461-470):
./artifacts/pypi-package/*./artifacts/windows-exe-x64/*./artifacts/linux-exe-x64/*, ./artifacts/linux-exe-arm64/*./artifacts/macos-exe-x64/*, ./artifacts/macos-exe-arm64/*./artifacts/debian-*/*A simplified PyPI publishing workflow exists separately from the main package build pipeline at .github/workflows/publish-to-pypi.yml1-51 This workflow:
This lightweight workflow enables faster PyPI updates when executable builds are not needed.
Simplified PyPI Workflow
The workflow uses PyPI's trusted publishing feature, which eliminates the need for long-lived API tokens. The id-token: write permission (.github/workflows/publish-to-pypi.yml43) allows GitHub Actions to obtain short-lived OIDC tokens that PyPI accepts for authentication.
Sources: .github/workflows/publish-to-pypi.yml1-51
The build pipeline includes verification steps at multiple stages:
twine check dist/* to validate package metadata and structure (.github/workflows/build-packages.yml58-60)While not part of the distribution pipeline itself, unit tests run on pull requests and commits via .github/workflows/unittest.yml1-46 The test suite includes:
Tests run on both minimum Python version (3.8) and latest Python version (3.14) to ensure compatibility across the supported range.
Sources: .github/workflows/unittest.yml1-46 etc/unittest/backend.py23-56 etc/unittest/main.py8-17
The complete distribution pipeline produces the following artifacts for each release:
| Artifact Type | Count | Naming Pattern | Size Range |
|---|---|---|---|
| PyPI packages | 2 | g4f-{version}-py3-none-any.whlg4f-{version}.tar.gz | ~500KB wheel ~1MB source |
| Windows executables | 1 | g4f-windows-{version}-x64.zip | ~50-100MB |
| Linux executables | 2 | g4f-linux-{version}-x64g4f-linux-{version}-arm64 | ~50-100MB each |
| macOS executables | 2 | g4f-macos-{version}-x64g4f-macos-{version}-arm64 | ~50-100MB each |
| Docker images | 6 | hlohaus789/g4f:{version}hlohaus789/g4f:latest-slim and -armv7 variants | Variable by variant |
| WinGet manifests | 3 | g4f.yamlg4f.installer.yamlg4f.locale.en-US.yaml | ~1KB each |
All artifacts are version-stamped with the git tag version and made available simultaneously through GitHub releases.
Refresh this wiki