Installation

Prefect requires Python 3.8 or newer.

We recommend installing Prefect using a Python virtual environment manager such as pipenv, conda, or virtualenv/venv.

You can use Prefect Cloud as your API server or host your own Prefect server instance backed by PostgreSQL. For development, you can use SQLite 2.24 or newer as your database.

Prefect Cloud is a managed solution that provides strong scaling, performance, and security. Learn more about Prefect Cloud solutions for enterprises here.

Windows and Linux requirements

See Windows installation notes and Linux installation notes for details on additional installation requirements and considerations.

Install Prefect

The following sections describe how to install Prefect in your environment.

Installing the Prefect 2 latest version

Prefect is published as a Python package. To install the latest Prefect 2 release run the following command in your terminal:

pip install 'prefect<3'

See the Prefect 3 docs to learn about the benefits of Prefect 3 and how to install it.

To install a specific Prefect version, specify the version number like this:

pip install "prefect==2.17.1"

See available release versions in the Prefect Release Notes.

See our Contributing guide for instructions on installing Prefect for development and see the section below to install directly from the main branch.

Checking your installation

To confirm that Prefect was installed correctly, run the command prefect version in your terminal.

prefect version

You should see output similar to the following:

Version:             2.17.1
API version:         0.8.4
Python version:      3.12.2
Git commit:          d6bdb075
Built:               Thu, Apr 11, 2024 6:58 PM
OS/Arch:             darwin/arm64
Profile:              local
Server type:         ephemeral
Server:
  Database:          sqlite
  SQLite version:    3.45.2

Windows installation notes

You can install and run Prefect via Windows PowerShell, the Windows Command Prompt, or conda. After installation, you may need to manually add the Python local packages Scripts folder to your Path environment variable.

The Scripts folder path looks something like this (the username and Python version may be different on your system):

C:\Users\MyUserNameHere\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.11_qbz5n2kfra8p0\LocalCache\local-packages\Python311\Scripts

Watch the pip install output messages for the Scripts folder path on your system.

If you're using Windows Subsystem for Linux (WSL), see Linux installation notes.

Linux installation notes

Linux is a popular operating system for running Prefect. If you are hosting your own Prefect server instance with a SQLite database, note that certain Linux versions of SQLite can be problematic. Compatible versions include Ubuntu 22.04 LTS and Ubuntu 20.04 LTS.

Alternatively, you can install SQLite on Red Hat Custom Linux (RHEL) or use the conda virtual environment manager and configure a compatible SQLite version.

Using a self-signed SSL certificate

If you're using a self-signed SSL certificate, you need to configure your environment to trust the certificate. You can add the certificate to your system bundle and pointing your tools to use that bundle by configuring the SSL_CERT_FILE environment variable.

If the certificate is not part of your system bundle, you can set the PREFECT_API_TLS_INSECURE_SKIP_VERIFY to True to disable certificate verification altogether.

Note: Disabling certificate validation is insecure and only suggested as an option for testing!

Proxies

Prefect supports communicating via proxies through environment variables. Whether you are using Prefect Cloud or hosting your own Prefect server instance, set HTTPS_PROXY and SSL_CERT_FILE in your environment, and the underlying network libraries will route Prefect’s requests appropriately.

Alternatively, the Prefect library will connect to the API via any proxies you have listed in the HTTP_PROXY or ALL_PROXY environment variables.
You may also use the NO_PROXY environment variable to specify which hosts should not be sent through the proxy.

For more information about these environment variables, see the cURL documentation.

prefect-client library

The prefect-client library is a minimal installation of Prefect designed for interacting with Prefect Cloud or a remote self-hosted server instance.

prefect-client enables a subset of Prefect's functionality with a smaller installation size, making it ideal for use in lightweight, resource-constrained, or ephemeral environments. It omits all CLI and server components found in the prefect library.

Install with:

pip install 'prefect-client<3'

SQLite

By default, a local Prefect server instance uses SQLite as the backing database. SQLite is not packaged with the Prefect installation. Most systems will already have SQLite installed, because it is typically bundled with Python.

Note

Note that in production we recommend using Prefect Cloud as your API server or hosting your own Prefect server instance backed by PostgreSQL.

Info

If you install the prefect-client library that provides a limited set of the full Prefect library's functionality, you do not need SQLite installed.

Install SQLite on RHEL

To install an appropriate version of SQLite on Red Hat Custom Linux (RHEL), follow the instructions below:

Expand for instructions

Note that some RHEL instances have no C compiler, so you may need to check for and install `gcc` first:

yum install gcc

Download and extract the tarball for SQLite.

wget https://www.sqlite.org/2022/sqlite-autoconf-3390200.tar.gz
tar -xzf sqlite-autoconf-3390200.tar.gz

Move to the extracted SQLite directory, then build and install SQLite.

cd sqlite-autoconf-3390200/
./configure
make
make install

Add `LD_LIBRARY_PATH` to your profile.

echo 'export LD_LIBRARY_PATH="/usr/local/lib"' >> /etc/profile

Restart your shell to register these changes. Now you can install Prefect using `pip`.

pip3 install 'prefect<3'

Next steps

Now that you have Prefect installed and your environment configured, check out the Tutorial to get more familiar with Prefect.