Skip to content

Development Setup

All actions mentioned in this page should be performed under the repository root folder i.e. ./Blender-Launcher-V2.

Requirements

  • Python >=3.11, <3.15
  • UV (optional)

It’s entirely optional to use uv as the project manager, but is strongly recommended as we use its tooling such as its lockfile and dependency resolution. Every shell snippet in this doc after the “Setting Up” step will use uv run as a prefix to indicate it needs to be run in the virtual environment.

Setting Up Development Environment

# Install virtualenv:
python -m pip install virtualenv
# Create the virtual environment
python -m virtualenv --clear --download .venv

Activate the virtual environment:

./.venv/Scripts/activate.ps1

./.venv/Scripts/activate

source .venv/bin/activate

Install dependencies:

# Minimum set of packages for building the executable:
pip install -e .
# All packages including development tools
pip install -e ".[docs,ruff,pytest]"

# Create the virtual environment & install dependencies:
pdm install
# Install with all development groups:
pdm install -G:all

Activate the virtual environment:

./.venv/Scripts/activate.ps1

./.venv/Scripts/activate

source .venv/bin/activate

Or run commands directly with PDM:

pdm run python source/main.py

# Create the virtual environment & install dependencies
uv sync --frozen
# install with all extras (docs, ruff, pytest)
uv sync --all-extras

Activate the virtual environment:

./.venv/Scripts/activate.ps1

./.venv/Scripts/activate

source .venv/bin/activate

Or run commands directly with UV:

uv run source/main.py

Running Blender Launcher1

# Generate the cached resource files:
# This creates necessary files like `resources_rc.py` and `global.qss`.
# This only needs to run once, unless you're updating widget styles.
uv run build_style.py

# Run the application
uv run source/main.py

Building Blender Launcher Executable2

Build the executable

Run the build script:

uv run ./scripts/build_win.bat

uv run sh ./scripts/build_linux.sh

uv run sh ./scripts/build_mac.sh

These scripts will create a standalone executable using PyInstaller. Once finished, the executable can be found under the Blender-Launcher-V2/dist/release folder.

Documentation

Previewing the Documentation

cd docs
# prefix with `uv run` if not in the virtual env
uv run mkdocs serve --livereload
or use the provided scripts/mkdocs_serve scripts.

Then open the given link (likely http://127.0.0.1:8000/) in a web browser.

Edit Documentation Files3

Make the desired modifications in the .md files under the docs/mkdocs directory.

Publish the Documentation [Collaborator Only]4

cd docs
uv run mkdocs gh-deploy

or use the provided scripts/mkdocs_publish scripts.

This builds and publishes the documentation to the gh-pages branch.

Common Development Tasks

Running Tests

uv run pytest

Code Formatting and Linting

Check code with Ruff:

ruff check .

Format code with Ruff:

ruff format .

  1. As of (c90f33d ~v2.4.0), cached Blender-Launcher-V2 files (such as resources_rc.py and global.qss) are no longer included in the source due to them artificially inflating git diffs.

    In order to generate them, run the build_style.py script located in the root project directory. Running Blender Launcher without these being built will result in an error. ↩

  2. Cross-platform compilation

    Executables made in PyInstaller must be built inside the target platform. You cannot build for a different platform other than your own.

    ↩

  3. You should never edit the documentation in the gh-pages branch; this branch is used to publish the documentation and is overwritten every time mkdocs gh-deploy is run. ↩

  4. These scripts will only work if you have write access to the Blender-Launcher-V2 repo. ↩