Project Basics#

However you create a project — in VSCode or from the CLI — a JITX project has the same shape: a Python package containing your design code, plus a pyproject.toml that declares its dependencies. This page covers that anatomy and how to manage dependencies, which work the same in both workflows.

Project structure#

A newly created project looks like this (here named myboard):

myboard/
├── pyproject.toml      # project metadata and dependencies
├── .gitignore
├── .vscode/            # editor config (settings, launch, tasks)
└── myboard/            # your design package
    ├── __init__.py
    └── main.py         # your design code

Understanding the files#

main.py is your main design file — it defines your circuit and its configuration. A new project’s main.py starts with a worked example: a simple resistor circuit wired in parallel, with configurable component defaults.

pyproject.toml holds your project metadata and the list of Python dependencies. Those dependencies are installed into the project’s virtual environment.

Generated output#

Building a design writes its output under a designs/ directory, in a folder named after the design’s fully-qualified name (e.g. myboard.main.myboard):

myboard/
└── designs/
    └── myboard.main.myboard/
        └── design-info/
            ├── schematic.design
            └── physical-layout.design

These files are generated from your design code. JITX also creates local caches (parts-db/, designs/**/cache/); the scaffolded .gitignore keeps those out of version control.

Virtual environments#

A JITX project runs inside a Python virtual environment — an isolated, per-project Python with its own copy of jitx and the libraries your design depends on. This keeps each project’s pinned versions separate from your system Python and from other projects, and makes the project reproducible for collaborators.

  • In VSCode, the extension creates and activates the environment (.venv) for you automatically.

  • From the CLI, you create and activate it yourself — see Creating a New Project.

New to virtual environments? The Python Packaging User Guide’s Install packages in a virtual environment using pip and venv is a good introduction.

Managing dependencies#

Dependencies are declared in the [project].dependencies section of pyproject.toml:

[project]
name = "my-project"
dependencies = [
    "jitx>=4.0",
    "other-fancy-dependency>=1.23",
]

Add new libraries, or constrain versions, by editing this list directly.

Warning

Treat pyproject.toml as the complete description of your project’s environment. Avoid pip install-ing packages outside it: manually-installed packages aren’t recorded there, so the project won’t reproduce reliably for collaborators — or for you on another machine.

Upgrading dependencies#

JITX can upgrade your declared dependencies to the latest compatible versions, and pull in any you’ve added to pyproject.toml by hand:

  • In VSCode — open the Command Palette (Cmd/Ctrl+Shift+P) and run JITX: Upgrade Dependencies.

  • From the CLI — run jitx project dependencies upgrade in your project. Use jitx project dependencies check to preview the available updates first.