Creating a New Project#

This guide walks through scaffolding a JITX project, setting up its environment, installing the matching JITX runtime, and signing in — the one-time setup for a project. It assumes you’ve installed the CLI.

Scaffold the project#

With uv:

uvx jitx project layout init myboard --name myboard

If you bootstrapped with pip instead of uv:

source ~/.venvs/jitx/bin/activate
jitx project layout init myboard --name myboard
deactivate

init takes an optional path to scaffold into (default: the current directory) and --name to set the package and design name. It writes a complete project skeleton:

Path	Purpose
`pyproject.toml`	Project metadata and Python dependencies (including `jitx` itself)
`myboard/main.py`	A sample design to start from
`myboard/__init__.py`	Marks the design package
`.gitignore`	Sensible ignores for a JITX project
`.vscode/`	Editor config, so the same project also opens cleanly in VSCode

Existing files are preserved; pass --force to overwrite, or re-run later to regenerate the editor config.

For what each of these files is, and how dependency management works, see Project Basics.

Scaffolding is the only step that uses the bootstrap install from Installation — everything from here on runs from the project’s own environment. If you bootstrapped with pip, feel free to delete ~/.venvs/jitx; with uvx there’s nothing to clean up.

Create a virtual environment#

Work inside a project-local virtual environment so the project’s dependencies stay isolated from the rest of your system. The convention — and what the scaffolded .gitignore already excludes — is a .venv directory in the project root:

cd myboard
uv venv                       # with uv
# or
python -m venv .venv          # with pip

Then activate it:

source .venv/bin/activate     # macOS / Linux
# .venv\Scripts\activate      # Windows

When the environment is active, your shell prompt is prefixed with (.venv), and python and jitx resolve to the project’s environment. Activation lasts only for the current terminal session — open a new terminal and you’ll need to activate it again before running jitx. To leave the environment, run deactivate.

New to virtual environments? See Project Basics for what they are and why JITX uses one.

Install the project’s dependencies#

A JITX project is a Python package, and the CLI imports your design code by module name. Install the project into the environment in editable mode so the CLI sees your latest code without reinstalling:

uv pip install -e .   # with uv
# or
pip install -e .      # with pip

The -e (editable) flag matters: your design lives in your source tree, and JITX imports it by name every time you run a command. A plain, non-editable install would snapshot the code at install time and miss your subsequent edits.

This step also installs jitx into the environment, so with the venv active, jitx resolves to the project’s .venv and you can run it directly (no uvx prefix needed).

Tip

If you’re using uv, one command does both steps: uv sync creates .venv and installs the project in editable mode, recording the resolved dependency versions in a uv.lock file (commit it to share exact versions with collaborators). uv also doesn’t require the environment to be active: uv pip install -e . finds .venv on its own, and uv run jitx find runs any command inside it. The rest of this guide assumes an activated environment so the bare jitx commands work as written — if you skip activation, prefix them with uv run.

List your designs#

Confirm JITX can discover the design in your project:

jitx find

designs:
  myboard.main.myboard

The fully-qualified name (myboard.main.myboard) is how you refer to a design when building it.

Install the runtime#

JITX uses a separate backend component, the JITX runtime, that ships outside the Python package. The CLI needs it present on your system before you can sign in or build, so install it now, with the project’s environment active:

jitx runtime install

With no version specified, this installs the runtime that matches the jitx package in the active environment — and that’s exactly why we install it from inside the project: the runtime follows the jitx version your project pins in pyproject.toml, not whatever happens to be newest. To install a specific runtime instead, pass --version:

jitx runtime install --version <version>

If you’ve used JITX in VSCode on this machine, the runtime is already installed — confirm with jitx runtime introspect, which reports the installed version (the version field) along with the rest of the runtime’s configuration.

You install the runtime once per version; you’ll start it each working session, when you build or edit a design.

Supported platforms#

The runtime is built and tested for three hosts, where the right artifact is detected automatically:

Host	`--target`
Ubuntu (not under WSL)	`ubuntu`
macOS — any version, Intel or Apple Silicon	`macos`
Windows (not under WSL)	`windows`

On any other host — a different Linux distribution (Arch, Debian, Pop!_OS, Fedora, …), WSL, or an unrecognized platform — JITX won’t guess. Instead, jitx runtime install stops and asks you to pick an artifact (the distribution name reflects your host):

Error: JITX is not tested on Linux distribution 'arch'. Pass --target to pick an artifact (the ubuntu build runs on most glibc Linux).
  Available --target values: ubuntu, macos, windows

Re-run with --target to choose one:

jitx runtime install --target ubuntu

The ubuntu build runs on most glibc-based Linux distributions, so --target ubuntu is the right choice on Arch, Debian, Fedora, and similar. Under WSL, use --target ubuntu to run JITX inside WSL, or install the Windows build on the host instead.

Sign in#

With the runtime installed (signing in requires it), authenticate against your JITX account:

jitx auth login

You’ll be prompted for the email and password of your JITX account. For scripting, pass --email to skip the email prompt and --password-stdin to pipe the password in instead of typing it.

Check your current status at any time:

jitx auth show

Once you’re signed in, your project is fully set up. Next, build and edit your design.