frigobar 10

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

Using a custom pyproject.toml path:

frigobar my_script.py -t /path/to/custom/pyproject.toml

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

Environment Variables

You can set environment variables that will be available when the script runs:

frigobar my_script.py --env-var MY_VAR=value --env-var ANOTHER_VAR=123

These environment variables will be set in the generated batch file and will be available to your Python script when it runs.

Copying Directories

By default, Frigobar only copies the script file to the distribution. However, you can copy the entire directory containing the script or a specific directory.

Copy the script's directory:

frigobar my_script.py --copy-directory

Copy a specific directory (the script must be inside it):

frigobar --include-directory /path/to/directory my_script.py

Both options respect .gitignore patterns if a .gitignore file is present in the source directory.

Custom run template

By default, the generated batch file will run uv run my_script.py. For more complex scenarios, you can specify a custom template for the uv run command in the generated batch file with the --run-template option. Use {script} as a placeholder for the script path. The template will be used as the argument to uv run.

For example, if your script use Gunicorn:

frigobar my_script.py --run-template "gunicorn --chdir script/src my_app.main:app --workers 4"

will generate a batch file that runs uv run gunicorn --chdir script/src my_app.main:app --workers 4, instead of the default uv run "script\my_script.py".

Or for a Streamlit app:

frigobar my_script.py --run-template "streamlit run {script} --server.port 8501"

will generate a batch file that runsuv run streamlit run "script\my_script.py" --server.port 8501.

Note: The template is applied after uv run, so it cannot replace the uv run part itself.

Installation

pip install frigobar

Options

> frigobar --help
usage: cli.py [-h] [-t PYPROJECT_FILE] [-r REQUIREMENTS_FILE] [-p PYTHON_VERSION] [--copy-directory] [--include-directory INCLUDE_DIRECTORY] [-e ENV_VAR] 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
  -t PYPROJECT_FILE, --pyproject-file PYPROJECT_FILE
                        Path to a pyproject.toml file that contains the dependencies of the script. If not provided, the tool will look for a pyproject.toml file in the script's directory. Cannot be used together with --requirements-file.
  -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. Cannot be used together with --include-directory.
  --include-directory INCLUDE_DIRECTORY
                        Copy the specified directory to the distribution. The script must be located inside this directory. Respects .gitignore if present. Cannot be used together with --copy-directory.
  -e ENV_VAR, --env-var ENV_VAR
                        Set environment variables in the generated batch file. Format: KEY=VALUE. Can be used multiple times to set multiple variables. Example: --env-var MY_VAR=value --env-var ANOTHER_VAR=123
  --run-template RUN_TEMPLATE
                        Custom template for the run command in the batch file. Use {script} as a placeholder for the script path. If not provided, defaults to 'uv run {script}'. Example: --run-template 'python {script}'

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.