Complete Guide: Adding User Extensions to Flet

This comprehensive guide will walk you through the process of adding custom user extensions to your Flet applications. Perfect for beginners who want to extend Flet's functionality with community-created widgets and components.

Table of Contents

Prerequisites

Before starting, make sure you have:

Step 1: Install UV Package Manager

UV is a fast Python package manager that we'll use for dependency management.

Install UV globally:

pip install uv
What this does: Installs the UV package manager globally on your system, making it available from any directory.

Step 2: Create Virtual Environment

A virtual environment keeps your project dependencies isolated from your system Python.

Create virtual environment:

uv venv

Activate the virtual environment:

For macOS/Linux:

source .venv/bin/activate

For Windows:

.venv\Scripts\activate

What this does:

How to know it's active: You'll see (.venv) at the beginning of your terminal prompt.

Step 3: Install Flet

Install Flet with all optional dependencies:

uv pip install flet[all]==0.28.3
What this does: Installs Flet version 0.28.3 with all optional features enabled, giving you access to all Flet widgets and capabilities.

Step 4: Create New Project (Optional)

If you don't have an existing project, create a new one:

uv run flet create test_app
Replace test_app with your desired project name.

What this does: Creates a new Flet project with the following structure:

test_app/
├── pyproject.toml          # Project configuration
├── README.md              # Project documentation
├── src/
│   ├── main.py           # Main application file
│   └── assets/           # Static files (images, etc.)

Step 5: Project Setup

Navigate to your project directory:

cd test_app

Sync dependencies:

Option 1: From project directory (recommended):

uv sync

Option 2: Specify path to project directory:

uv sync --project /path/to/your/project

Examples with absolute paths (full paths):

# If you're already in the project directory (where pyproject.toml is located)
uv sync

# Absolute paths (full paths from root)
uv sync --project /Users/username/Desktop/my_awesome_app
uv sync --project /home/username/projects/flet_app
uv sync --project ~/my_flet_projects/test_app

# On Windows (absolute paths)
uv sync --project C:\Users\username\Desktop\my_awesome_app
uv sync --project "C:\Program Files\MyProjects\flet_app"

Examples with relative paths:

# Relative to current directory
uv sync --project ./my_project
uv sync --project ../parent_folder/my_project
uv sync --project ../../other_projects/flet_app

# Go up one level and into project folder
uv sync --project ../test_app

# Current directory (same as just 'uv sync')
uv sync --project .

What this does:

Important: uv sync requires a pyproject.toml file to work. If you run it from a directory without this file, you'll get an error.

Virtual environment behavior: If you run uv sync in a directory that contains pyproject.toml but doesn't have a .venv folder, UV will create a new virtual environment in that directory. This is why it's important to use --project to specify the correct project path, or make sure you're in the right directory to avoid creating unwanted .venv folders.

Step 6: Adding Extensions

Extensions are added by modifying the pyproject.toml file in your project root.

Open pyproject.toml and locate the dependencies section:

dependencies = [
    "flet==0.28.3"
]

Add your extensions to this list

Method 1: From GitHub Repository

For extensions hosted on GitHub, use this format:

dependencies = [
    "flet==0.28.3",
    "flet-animated-border @ git+https://github.com/Wanna-Pizza/flet-animated-border.git@main"
]

Format explanation:

Method 2: From PyPI

For extensions published on PyPI:

dependencies = [
    "flet==0.28.3",
    "flet-custom-widget==1.2.3"
]

Install the new dependencies:

uv sync
What this does: Downloads and installs the new extensions and their dependencies.

Step 7: Building and Running

Build for your platform:

For macOS:

uv run flet build macos -v

For Windows:

uv run flet build windows -v

For Linux:

uv run flet build linux -v

What this does:

Run your application:

For macOS/Linux:

uv run flet run src/main.py

For Windows:

uv run flet run src\main.py

Alternative (hot reload for development):

For macOS/Linux:

uv run flet -r src/main.py

For Windows:

uv run flet -r src\main.py

What this does:

Examples

Example 1: Adding Multiple Extensions

dependencies = [
    "flet==0.28.3",
    "flet-animated-border @ git+https://github.com/Wanna-Pizza/flet-animated-border.git@main",
    "flet-charts @ git+https://github.com/example/flet-charts.git@v1.0",
    "flet-widgets==2.1.0"
]

Example 2: Using the Extension in Your Code

import flet as ft
from flet_animated_border import AnimatedBorder  # Import your extension

Example 3: Complete Workflow

For macOS/Linux:

# 1. Create project
uv run flet create my_awesome_app
cd my_awesome_app

# 2. Edit pyproject.toml to add extensions
# (add your extensions to the dependencies list)

# 3. Install dependencies
uv sync

# 4. Build for your platform
uv run flet build macos -v

# 5. Run with hot reload
uv run flet -r src/main.py

For Windows:

# 1. Create project
uv run flet create my_awesome_app
cd my_awesome_app

# 2. Edit pyproject.toml to add extensions
# (add your extensions to the dependencies list)

# 3. Install dependencies
uv sync

# 4. Build for your platform
uv run flet build windows -v

# 5. Run with hot reload
uv run flet -r src\main.py

Troubleshooting

Common Issues and Solutions

Issue: "uv: command not found"

Solution: UV is not installed. Run pip install uv first.

Issue: Virtual environment not activating

Solution: Make sure you're in the correct directory and using the right command for your OS.

Issue: Extension not found after installation

Solutions:

  1. Run uv sync after adding to pyproject.toml
  2. Make sure you've built the project: uv run flet build [platform] -v
  3. Check that the extension name is spelled correctly

Issue: Import errors when using extensions

Solutions:

  1. Ensure the extension is properly installed: uv list to see installed packages
  2. Check the extension's documentation for correct import syntax
  3. Make sure you've built the project for your platform

Issue: Build fails

Solutions:

  1. Check that all dependencies are compatible
  2. Try building with verbose output: uv run flet build [platform] -v
  3. Ensure you have the necessary system dependencies installed

Useful Commands

# Check installed packages
uv list

# Update all dependencies
uv sync --upgrade

# Remove a dependency
# (Edit pyproject.toml to remove the line, then run)
uv sync

# Check UV version
uv --version

Tips for Success

  1. Always build after adding extensions - This ensures custom widgets are available during development
  2. Use virtual environments - Keeps your projects isolated and manageable
  3. Pin versions - Specify exact versions in pyproject.toml for reproducible builds
  4. Test frequently - Run your app after each extension addition to catch issues early
  5. Read documentation - Each extension may have specific setup requirements

Congratulations! You now have a complete understanding of how to add and use user extensions in Flet. Start building amazing applications with the power of community-created widgets!