The first step to getting started with Prefect is installing the Prefect Python package.
Set up Python
Prefect requires Python 3.7 or later.
We recommend installing Prefect 2.0 using a Python virtual environment manager such as
The following sections describe how to install Prefect in your development or execution environment.
Installing the latest version
Prefect is published as a Python package. To install the latest 2.0 release, run the following in a shell or terminal session:
pip install -U "prefect>=2.0b"
To install a specific version, specify the version, such as:
pip install -U "prefect==2.0b6"
Installing the bleeding edge
If you'd like to test with the most up-to-date code, you can install directly off the
orion branch on GitHub:
pip install git+https://github.com/PrefectHQ/prefect@orion
orion branch may not be stable
Please be aware that this method installs unreleased code and may not be stable.
Installing for development
If you'd like to install a version of Prefect for development:
- Clone the Prefect repository.
- Check out the
- Install an editable version of the Python package with
pip install -e.
- Install pre-commit hooks.
$ git clone https://github.com/PrefectHQ/prefect.git $ git checkout orion $ pip install -e ".[dev]" $ pre-commit install
See our Contributing guide for more details about standards and practices for contributing to Prefect.
Checking your installation
To check that Prefect was installed correctly, use the Prefect CLI command
prefect version. Running this command should print version and environment details to your console.
$ prefect version Version: 2.0b6 API version: 0.5.0 Python version: 3.9.10 Git commit: 1594c9c5 Built: Mon, Jun 6, 2022 6:11 PM OS/Arch: darwin/x86_64 Profile: default Server type: ephemeral Server: Database: sqlite SQLite version: 3.32.3
Windows installation notes
Support for running Prefect flows on Windows became available with Prefect 2.0b6.
You can install and run Prefect as described above via Windows PowerShell, the Windows Command Prompt, or
conda. Note that, after installation, you may need to manually add the Python local packages
Scripts folder to your
Path environment variable.
Scripts folder path looks something like this (the username and Python version may be different on your system):
pip install installation output messages for the
Scripts folder path on your system.
If using Windows Subsystem for Linux (WSL), see Linux installation notes.
Windows support is under development
Support for Prefect on Windows is a work in progress.
Right now, we're focused on your ability to develop and run flows and tasks on Windows, along with running the API server, orchestration engine, and UI.
Linux installation notes
Currently, Prefect 2.0 requires SQLite 3.24 or newer.
When installing Prefect 2.0 and using a SQLite backend on Linux, make sure your environment is using a compatible SQLite version. Some versions of Linux package a version of SQLite that cannot be used with Prefect 2.0.
Known compatible releases include:
- Ubuntu 20.04 LTS
You can also:
- Use the
condavirtual environment manager, which enables configuring a compatible SQLite version.
- Configure a PostgeSQL database as the Prefect backend database.
- Use Prefect Cloud as your API server and orchestration engine.
Upgrading to 2.0b6
In Prefect 2.0b6 we've added breaking changes with respect to the Blocks API. This API is an important abstraction you may have used already to create default Storage or specifying
flow_storage as part of a
DeploymentSpec. As a result, the backend API in 2.0b6 is incompatible with previous Prefect client versions.
After the upgrade, your data will remain intact, but you will need to upgrade to 2.0b6 to continue using the Cloud 2.0 API.
Actions needed on your end to upgrade, especially as a Cloud 2.0 user:
- Upgrade Prefect 2.0 Python package:
pip install -U "prefect>=2.0b6"
- Restart any agent processes.
- If you are using an agent running on Kubernetes, update the Prefect image version to 2.0b6 in your Kubernetes manifest and re-apply the deployment.
You don't need to recreate any deployments or pause your schedules - stopping your agent process to perform an upgrade may result in some late runs, but those will be picked up once you restart your agent, so Don't Panic!
Upgrading to 2.0a10
Upgrading from Prefect version 2.0a9 or earlier requires resetting the Prefect Orion database.
Prior to 2.0a10, Prefect did not have database migrations and required a hard reset of the database between versions. Now that migrations have been added, your database will be upgraded automatically with each version change. However, you must still perform a hard reset of the database if you are upgrading from 2.0a9 or earlier.
Resetting the database with the CLI command
prefect orion database reset is not compatible a database from 2.0a9 or earlier. Instead, delete the database file
~/.prefect/orion.db. Prefect automatically creates a new database on the next write.
Resetting the database deletes data
Note that resetting the database causes the loss of any existing data.
While Prefect works with many of your favorite tools and Python modules, it has a few external dependencies.
Prefect 2.0 uses SQLite as the default backing database, but it is not packaged with the Prefect installation. Most systems will have SQLite installed already since it is typically bundled as a part of Python. Prefect requires SQLite version 3.24.0 or later.
You can check your SQLite version by executing the following command in a terminal:
$ sqlite3 --version
Or use the Prefect CLI command
prefect version, which prints version and environment details to your console, including the server database and version.
$ prefect version Version: 2.0b5 API version: 0.3.1 Python version: 3.9.10 Git commit: 7b27c7cf Built: Tue, May 17, 2022 4:54 PM OS/Arch: darwin/x86_64 Profile: default Server type: ephemeral Server: Database: sqlite SQLite version: 3.32.3