Create a project

Pyzed installs the pyzed command. It creates a complete project with uv, a tool that installs Python packages and keeps each project in its own environment (the pip and python tabs install uv for you):

uvx --from pyzed-ui pyzed new my-app     # uvx runs pyzed without installing it
cd my-app
uv run pyzed design     # open the main form in the visual designer
uv run pyzed run        # run the app

pip install pyzed-ui uv     # with your .venv active
pyzed new my-app
cd my-app
source .venv/bin/activate           # the project's own .venv
pyzed design         # open the main form in the visual designer
pyzed run            # run the app

pip install pyzed-ui uv     # with your .venv active
pyzed new my-app
cd my-app
.venv\Scripts\Activate.ps1           # the project's own .venv
pyzed design         # open the main form in the visual designer
pyzed run            # run the app

python3 -m pip install pyzed-ui uv
python3 -m pyzed new my-app
cd my-app
.venv/bin/python -m pyzed design     # open the main form in the visual designer
.venv/bin/python -m pyzed run        # run the app

py -m pip install pyzed-ui uv
py -m pyzed new my-app
cd my-app
.venv\Scripts\python -m pyzed design     # open the main form in the visual designer
.venv\Scripts\python -m pyzed run        # run the app

This generates a standard uv project:

my-app/
├── pyproject.toml     # dependencies (pyzed-ui; ruff and ty for development) + [tool.pyzed]
├── uv.lock
├── .venv/
├── .git/
├── src/my_app/        # backend
└── ui/                # forms (.pzform) and their event handlers (.py)

The UI folder keeps the interface apart from the rest of the code, and its handlers can import the backend, any module of the project and every dependency. Already have a project made with uv init? Run pyzed init inside it. See Projects with uv for the layout, dependency commands and the designer’s Project tab, and Build and distribute to package the app for each platform.

A single-file app

To start from code instead of the designer, --script creates one main.py without uv:

uvx --from pyzed-ui pyzed new my-app --script
cd my-app
uv run --with pyzed-ui main.py

pyzed new my-app --script     # with your .venv active
cd my-app
python main.py

python3 -m pyzed new my-app --script
cd my-app
python3 main.py

py -m pyzed new my-app --script
cd my-app
py main.py

The template already includes:

A ui.workspace with a title bar, left panel and status bar.
Navigation between pages with ui.list_item.
A command palette that opens with Ctrl+Shift+P and closes with Esc.
A button to switch between light and dark themes.

Find icons

Pyzed includes the ~2000 Lucide icons. To search for names:

uv run pyzed icons folder
# folder, folder-open, folder-git, folder-plus, ...

pyzed icons folder
# folder, folder-open, folder-git, folder-plus, ...

python3 -m pyzed icons folder
# folder, folder-open, folder-git, folder-plus, ...

py -m pyzed icons folder
# folder, folder-open, folder-git, folder-plus, ...

Use them with pz.icon("folder") or with the icon= parameter of components.

Run as a module

python -m pyzed is equivalent to the pyzed command:

uv run python -m pyzed new another-app

python -m pyzed new another-app

python3 -m pyzed new another-app

py -m pyzed new another-app