Skip to content

Conversation

@Creative-Geek
Copy link

Description

This PR adds a warning to the uv installation guide regarding a specific compatibility issue on Windows.

The Problem

When using uv to manage a Flet project on Windows, running uv run flet run main.py causes the application to exit silently with code 0. No GUI window appears, and no error is thrown. Setting FLET_LOG_LEVEL=debug produces no output.

Investigation (Skip Reading This)

I encountered this issue personally and went through extensive debugging:

  1. Verification: Validated that the exact same script works perfectly when using a standard venv created by python -m venv.
  2. Environment: Tested across different terminals (Git Bash, PowerShell, CMD) with the same silent failure result.
  3. Dependencies: Attempted pinning Python versions and websockets versions to rule out library conflicts.
  4. Root Cause: I discovered that the issue stems from how uv links packages in the virtual environment. Flet's internal logic for locating its binaries/assets fails when uv uses symbolic links on Windows.

The Solution

The issue is resolved by forcing uv to physically copy files instead of linking them. Configuring [tool.uv] link-mode = "copy" in pyproject.toml fixes the silent crash immediately.

Changes

  • Added a :::warning block to the uv section of the Getting Started guide (which is the only place where uv is directly mentioned).

Add warning about symbolic links on Windows for Flet apps.
@CLAassistant
Copy link

CLAassistant commented Dec 9, 2025

CLA assistant check
All committers have signed the CLA.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants