NiceGUI Project Template

Prerequisites

pipx is used to install tools like copier independent of other tools' or projects' dependencies:

1. install pipx according to the documentation here.
2. install copier with pipx: pipx install copier (tested with copier==9.7.1).
3. it's recommended to use a virtual environment. If you don't have virtualenv installed, install it with: pipx install virtualenv.
4. if you want to use Poetry for managing your project's dependencies, install Poetry: pipx install poetry (tested with poetry==2.2.1).
5. if you want to use uv for managing your project's dependencies, install uv: pipx install uv (tested with uv==0.9.7) or see here for instructions.

Quickstart

1. generate your project:

copier copy git@github.com:zauberzeug/nicegui-template.git path/to/project

2. explore your new project:

cd path/to/project

3. initialize a git repo:

git init

Now you can connect your local repository to GitHub by creating a new repository. Pay attention to not add a README.md, etc. since your project already has all of this. GitHub then gives you the necessary commands to connect the origin to your local project. Look out for the part "…or push an existing repository from the command line" and run those commands.

4. create a virtual environment (you can skip this if you're using uv):

virtualenv .venv
# add -p $PATH_TO_PYTHON_EXECUTABLE to specify a python version, for example:
virtualenv .venv -p $PYENV_ROOT/versions/3.12.10/bin/python

source .venv/bin/activate # to activate your virtual environment

5. install standard dependencies to start working:

# with Poetry run first:
poetry lock

# then for all dependency management tools:
make sync

6. if you added pre-commit in step 1, do:

pre-commit install
git add .
git commit -m "initial commit"

7. start your project:

./main.py

Available Questions / Options

name	type	options	default	explanation
project name	str		-	the project's name as stated in the pyproject.toml
module name	str		same as project name	the name of the main module in the root directory of the project
project description	str		-	used in the pyproject.toml
dependency management	str	uv / pip / poetry	uv	choose a dependency management tool: uv, Poetry or just pip
use poetry dynamic versioning	boolean	true / false	false	use dynamic versioning for Poetry
python versions	str	3.9 to 3.15	[3.11, 3.12, 3.13, 3.14]	defines the required and supported python versions
use precommit	boolean	true / false	false	use pre-commit to check your changes before committing
use rosys	boolean	true / false	false	add RoSys framework to dependencies
include contributing	boolean	true / false	true	include CONTRIBUTING.md with development guidelines (only asked if AI instructions disabled)
include ai instructions	boolean	true / false	true	include AI agent instructions (AGENT.md, .github/copilot-instructions.md, .cursor/*, CONTRIBUTING.md)

Update your project with a new version of the template

To update your project from the template or change settings run:

copier update

This will prompt you to review and update your template settings interactively. You can add --skip-answered if you just want the new version, but keep your previous answers.

If you changed a lot of the original template files and have the feeling that not everything you expected to update was updated, you can also run:

copier recopy ./path_to_your_project

Be careful with this command, as it will overwrite any local changes you made to the template files. It's recommended to run this without uncommitted changes and then thoroughly review the changes generated by copier with git.

Contributing Guidelines

When include_contributing is enabled (default when AI instructions are disabled), a CONTRIBUTING.md file is generated with:

• Development setup instructions
• Coding style guidelines
• Workflow and testing guidelines
• Pull request checklist

AI Instructions

When include_ai_instructions is enabled (default), the template generates files to help AI coding assistants (GitHub Copilot, Cursor, etc.) understand your project better:

• CONTRIBUTING.md - Development guidelines and coding standards (mandatory, serves as the detailed reference)
• AGENTS.md - Focused AI agent guidelines with principles and AI-specific patterns
• .github/copilot-instructions.md - Brief GitHub Copilot instructions that reference the main files plus detailed review instructions (because it's the most common and straight forward AI review tool when using GitHub)
• .cursor/rules - Brief Cursor AI quick reference
• .cursor/commands/*.md - Custom Cursor commands (review-code, check-style, suggest-tests, explain-code, simplify)

Structure Philosophy: Following the NiceGUI approach, CONTRIBUTING.md contains the comprehensive coding standards and workflow, while AGENTS.md focuses on AI-specific principles. Tool-specific files (.cursor/rules, .github/copilot-instructions.md) are kept brief and reference the main files.