How to Contribute

Learn how to set up Prefect for development and experimentation.

Set up a development environment

First, download the source code and install an editable copy of the Prefect Python package:

# Clone the repository
git clone https://github.com/PrefectHQ/prefect.git
cd prefect

# We recommend using a virtual environment. Below we use venv

python -m venv .venv
source .venv/bin/activate

# Install the package with development dependencies

pip install -e ".[dev]"

# Set up pre-commit hooks for required formatting

pre-commit install

If you don’t want to install the pre-commit hooks, manually install the formatting dependencies with:

pip install $(./scripts/precommit-versions.py)

Run ruff check and ruff format.

After installation, you can run the test suite with pytest:

# Run all the tests
pytest tests

# Run a subset of tests

pytest tests/test_flows.py

Build the Prefect UI

If you intend to run a local Prefect server during development, first build the UI. See UI development for instructions.

Developer tooling

The Prefect CLI provides several helpful commands to aid development.

Start all services with hot-reloading on code changes (requires installation of UI dependencies):

prefect dev start

Start a Prefect API that reloads on code changes:

prefect dev api

UI development

Developing the Prefect UI requires installation of npm. We recommend using nvm to manage Node.js versions. Once installed, run nvm use from the root of the Prefect repository to initialize the proper version of npm and node.

Start a development UI that reloads on code changes:

prefect dev ui

Build the static UI (the UI served by prefect server start):

prefect dev build-ui

Docs development

We use Mintlify to host and build the documentation.

The main branch of the prefecthq/prefect GitHub repository is used to build the Prefect 3.0rc docs at docs-3.prefect.io temporarily.

The 2.x docs are hosted at docs.prefect.io and built from the 2.x branch of prefecthq/prefect.

Make sure you have a recent version of Node.js installed. We recommend using nvm to manage Node.js versions.

1. Clone this repository.
2. Run cd docs to navigate to the docs directory.
3. Run nvm use node to use the correct Node.js version.
4. Run npm i -g mintlify to install Mintlify.
5. Run mintlify dev to start the development server.

Your docs should now be available at http://localhost:3000.

See the Mintlify documentation for more information on how install Mintlify, build previews, and use Mintlify’s features while writing docs.

.mdx files are Markdown files that can contain JavaScript and React components. They are used to create interactive documentation.

Add database migrations

To make changes to a table, first update the SQLAlchemy model in src/prefect/server/database/orm_models.py. For example, to add a new column to the flow_run table, add a new column to the FlowRun model:

# src/prefect/server/database/orm_models.py

@declarative_mixin
class ORMFlowRun(ORMRun):
    """SQLAlchemy model of a flow run."""
    ...
    new_column = Column(String, nullable=True) # <-- add this line

Next, you will generate new migration files. You must generate a new migration file for each database type. Migrations are generated for whatever database type PREFECT_API_DATABASE_CONNECTION_URL is set to. See how to set the database connection URL for each database type.

To generate a new migration file, run:

prefect server database revision --autogenerate -m "<migration name>"

Make your migration name brief but descriptive. For example:

• add_flow_run_new_column
• add_flow_run_new_column_idx
• rename_flow_run_old_column_to_new_column

The --autogenerate flag automatically generates a migration file based on the changes to the models.

Always inspect the output of --autogenerate

--autogenerate generates a migration file based on the changes to the models. However, it is not perfect. Check the file to make sure it only includes the changes you want. Additionally, you may need to remove extra statements that were included and not related to your change.

The new migration is in the src/prefect/server/database/migrations/versions/ directory. Each database type has its own subdirectory. For example, the SQLite migrations are stored in src/prefect/server/database/migrations/versions/sqlite/.

After you inspect the migration file, you can apply the migration to your database by running:

prefect server database upgrade -y

Once you successfully create and apply migrations for all database types, update MIGRATION-NOTES.md to document your additions.