frigobar 7

Distribute Python scripts to Windows machines without freezing them.

Frigobar

Distribute Python scripts to Windows machines without freezing them.

Basic usage

frigobar my_script.py

This will create a frigobar folder, with a my_script.bat file in it. Run it to run your app.

Advanced usage

Frigobar supports two modes of dependency management:

Modern dependencies (Recommended)

In this mode, you declare your dependencies either in a pyproject.toml file in the same directory as your script, or using inline script metadata (PEP 723) directly in your script file.

Frigobar will automatically detect pyproject.toml or inline metadata and configure the distribution to use uv for dependency resolution and Python version management.

Example with inline metadata:

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests",
#     "pandas",
# ]
# ///
import requests
import pandas

Usage:

frigobar my_script.py

Classical dependencies

In this mode, you provide a standard requirements.txt file. You can also optionally specify the Python version to be used.

Usage:

frigobar my_script.py -r requirements.txt

Or specifying a Python version:

frigobar my_script.py -r requirements.txt -p 3.12.0

Installation

pip install frigobar

Options

> frigobar --help
usage: cli.py [-h] [-r REQUIREMENTS_FILE] [-p PYTHON_VERSION] [--copy-directory] script-path [target-directory]

Distribute Python scripts to Windows machines without freezing them. The folder of the resulting distribution can be copied to any Windows machine. Users should run "<script_name>.bat" to run the script. All the dependencies, including Python, will be downloaded and installed on the first run.

positional arguments:
  script-path           Path to the script to distribute.
  target-directory      Folder where the distribution will be put. Defaults to 'frigobar'.

options:
  -h, --help            show this help message and exit
  -r REQUIREMENTS_FILE, --requirements-file REQUIREMENTS_FILE
                        Path to a classical requirements file (usually called requirements.txt) that lists the dependencies of the script. If not provided, dependencies must be declared in a pyproject.toml file or inline.
  -p PYTHON_VERSION, --python-version PYTHON_VERSION, --python PYTHON_VERSION
                        Python version, in X.Y.Z format, that the distribution should use. Only works when --requirements-file is specified. If not provided, the latest Python supported by the final user's system will be used.
  --copy-directory      Copy the contents of the script directory to the distribution. Respects .gitignore if present.

Rationale

A common technique to distribute Python apps is to "freeze" them using tools like PyInstaller or cx_Freeze. These freezers create a standalone executable that contains your app and all its dependencies. This is a workable solution, but it has two main drawbacks:

1. The resulting frozen app is often huge. It's not uncommon to see a simple app taking MBs of space.
2. Because dependence resolution is hard, the frozen app may contain more or less dependencies than it needs. Less dependencies lead to dread "working-app-that-stop-working-when-you-freeze-it" situations. Unnecessary dependencies lead to bloated apps.

Frigobar avoids those problems by postponing the download of the Python interpreter and all the app's dependencies to the first time the user runs the app, making the app the smallest it can be. Under the hood, Frigobar uses uv, an extremely fast Python package installer and resolver. This ensures a robust and reproducible environment setup, supporting both modern (pyproject.toml, inline metadata) and classical (requirements.txt) dependency definitions.