Skip to content

Getting Started

Welcome to FlavorPack! This guide will help you get up and running with creating your first Progressive Secure Package.

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

Package Name vs Tool Name

FlavorPack (or flavorpack) is the Python package name used for installation. The actual command-line tool and API is called flavor. Install with uv tool install flavorpack, use with flavor pack.

Quick Start Path

Follow these steps to get FlavorPack up and running:

1. Install FlavorPack ⚙️

Install FlavorPack and its native helper binaries. Use the standard install path or build from source if you need local changes.

Time: ~10 minutes Prerequisites: Python 3.11+, UV, Go 1.24+, Rust 1.85+

→ Installation Guide

2. Quick Start Tutorial 🚀

Create and run your first PSPF package in under 5 minutes with our step-by-step tutorial.

Time: ~5 minutes What you'll build: A simple "Hello World" package

→ Quick Start

3. Create Your First Real Package 📦

Build a complete Python application package with dependencies, configuration, and proper structure.

Time: ~15 minutes What you'll learn: Manifest configuration, dependencies, entry points

→ First Package Guide

4. Explore Examples 💡

See real-world examples of CLI tools, web apps, and more advanced packaging scenarios.

What's included: Complete working examples you can build and run

→ View Examples

Learning Paths

Choose the path that matches your goals:

For Beginners

Just want to package a Python app quickly?

  1. Installation - Get FlavorPack installed
  2. Quick Start - Your first package in 5 minutes
  3. Examples - Copy a working example similar to your needs

For Developers

Want to understand how everything works?

  1. Installation - Set up your environment
  2. Core Concepts - Understand PSPF format and architecture
  3. First Package - Build a complete package with best practices
  4. API Reference - Programmatic package creation

For DevOps Engineers

Need to integrate FlavorPack into CI/CD?

  1. Installation - Automated setup instructions
  2. CLI Reference - Command-line interface details
  3. CI/CD Recipes - Integration examples
  4. Environment Variables - Configuration options

Common Questions

What are the system requirements?

Minimum: Python 3.11, UV 0.8.13, Go 1.24, Rust 1.85 Recommended: Python 3.12+, latest UV, Go, and Rust Platforms: Linux (full), macOS (full), Windows (limited)

See Installation → System Requirements for details.

Is FlavorPack production-focused?

FlavorPack is an initial release. The core PSPF format and packaging features are available today, and exploratory improvements are still under evaluation.

How do I package a Python app with dependencies?

The most common workflow:

  1. Create a pyproject.toml manifest
  2. Run flavor pack --manifest pyproject.toml
  3. Your package is created as dist/<name>.psp

See First Package Guide for a complete walkthrough.

What's the difference between FlavorPack and PyInstaller?

FlavorPack creates PSPF packages with:

  • Cryptographic signing (Ed25519)
  • Smart caching (no re-extraction)
  • Cross-language support (Python, Go, Rust)
  • Native launchers (not Python-based)

PyInstaller creates traditional executables. FlavorPack is better for: - Security-conscious deployments - Large applications (caching helps) - Cross-platform distribution

See PSPF Format for technical details.

Can I package apps without Python installed?

Creating packages requires Python 3.11+ on the build machine.

Running packages does NOT require Python - the Python runtime is embedded in the .psp file. End users need nothing installed.

How do I troubleshoot installation issues?

Common issues and solutions:

  • UV not found: Add ~/.cargo/bin to PATH
  • Helper build fails: Verify Go/Rust versions
  • Permission denied: Run chmod +x on .psp files

See Installation Troubleshooting for complete guide.

Next Steps

  • Quick Start

    Get your first package built and running in under 5 minutes.

    Start Tutorial

  • First Package

    Build a complete application package with dependencies and configuration.

    Build Your Package

  • Core Concepts

    Understand the PSPF format, slots, operation chains, and security model.

    Learn Concepts

  • Examples

    Real-world examples of CLI tools, web apps, and advanced use cases.

    View Examples

Getting Help

If you run into issues or have questions:

  1. Troubleshooting Guide - Common issues and solutions
  2. FAQ - Frequently asked questions
  3. GitHub Issues - Report bugs or request features
  4. GitHub Discussions - Ask questions and share ideas

Ready to package your Python applications? Start with our Installation Guide →