Local setup

In this section we will set up your local environment so that you can start building and deploying Flyte workflows from your local machine.

Install uv

First, install uv.

Using uv as best practice

The uv tool is our recommended package and project manager. It replaces pip, pip-tools, pipx, poetry, pyenv, twine, virtualenv, and more.

You can, of course, use other tools, but all discussion in these pages will use uv, so you will have to adapt the directions as appropriate.

Ensure the correct version of Python is installed

Flytekit requires Python >=3.9,<3.13. We recommend using 3.12. You can install it with:

$ uv python install 3.12
Uninstall higher versions of Python

When installing Python packages “as tools” (as we do below with the flytekit), uv will default to the latest version of Python available on your system. If you have a version >=3.13 installed, you will need to uninstall it since flytekit requires >=3.9,<3.13.

Install the pyflyte CLI

Once uv is installed, use it to install the pyflyte CLI by installing the flytekit Python package:

$ uv tool install flytekit

This will make the pyflyte CLI globally available on your system.

Add the installation location to your PATH

uv installs tools in ~/.local/bin by default. Make sure this location is in your PATH, so you can run the pyflyte command from anywhere. uv provides a convenience command to do this: uv tool update-shell.

Note that later in this guide we will be running the pyflyte CLI to run your workflows. In those cases you will be running pyflyte within the Python virtual environment of your workflow project. You will not be using this globally installed instance of pyflyte. This instance of pyflyte is only used during the configuration step, below, when no projects yet exist.

Install Docker and get access to a container registry

Flyte tasks are run in containers. Every container requires a container image that defines its software environment. When developing and running Flyte tasks and workflows, an important part of the process is building those images and pushing them to a container registry. Your Flyte installation then pulls down these images when it spins up the containers that run your tasks.

To build and push the images you need to have Docker (or an equivalent container runtime) installed on your local machine.

Go to the Docker website for installation directions.

You will also need access to a container registry where you can push your images. Furthermore, the pushed images will need to be accessible to the Flyte installation you are using (The registry must be accessible and the images themselves must also have the appropriate permissions. For example, a public registry like ghcr.io with the images set to public, would work).

Flyte simplifies image building and registry

With Flyte you do not need to install Docker, build images, or deal with container registries. Flyte offers an in-cloud image builder and registry service that greatly simplifies this part of the development process.

Install flytectl to set up a local cluster

For production use you will need to install Flyte in your cloud infrastructure (see Deployment). Here we are using a local cluster for experimentation and demonstration purposes.

To set up a local cluster you must first install the flytectl CLI.

Flytectl vs Pyflyte

flytectl is different from the pyflyte.

pyflyte is a Python program and part of the flytekit SDK It is the primary command-line tool used during Flyte development.

flytectl is a compiled binary (written in Go) and used for performing certain administrative tasks. (see Flytectl for details)

To install flytectl, follow these instructions:

macOSLinuxWindows

To install flytectl on a Mac, use Homebrew, curl, or download the binary manually.

Homebrew

$ brew tap flyteorg/homebrew-tap
$ brew install flytectl

curl

To use curl, set BINDIR to the install location (it defaults to ./bin) and run the following command:

$ curl -sL https://ctl.flyte.org/install | sudo bash -s -- -b /usr/local/bin

Manual download

To download manually, see the flytectl releases.

To install flytectl on Linux, use curl or download the binary manually.

curl

To use curl, set BINDIR to the installation location (it defaults to ./bin) and run the following command (note that jq needs to be installed to run this script):

$ curl -sL https://ctl.flyte.org/install | sudo bash -s -- -b /usr/local/bin

Manual download

To download manually, see the flytectl releases.

To install flytectl on Windows, use curl , or download the binary manually.

curl

To use curl, in a Linux shell (such as WSL), set BINDIR to the install location (it defaults to ./bin) and run the following command:

$ curl -sL https://ctl.flyte.org/install | sudo bash -s -- -b /usr/local/bin

Manual download

To download manually, see the flytectl releases.

Start Docker and the local cluster

Once you have installed Docker and flytectl, do the following:

  1. Start the Docker daemon.

  2. Use flytectl to set up a local Flyte cluster by running:

$ flytectl demo start

This will start a local Flyte cluster on your machine and place a configuration file in ~/.flyte/config-sandbox.yaml that contains the connection information to connect pyflyte (and flytectl) to that cluster.

The local Flyte cluster will be available at localhost:30080.

Try Flyte technology through Flyte Serverless

Alternatively, you can try using Flyte technology through Flyte Serverless. With Flyte Serverless you do not need to install a local cluster and can start experimenting immediately on a full cloud deployment. You can even use the Workspaces in-browser IDE to quickly iterate on code. See Flyte Serverless > Getting started for more details.

Configure the connection to your Flyte instance

To configure the connection from pyflyte and flytectl to your Flyte instance, set the FLYTECTL_CONFIG environment variable to point to the configuration file that flytectl created:

$ export FLYTECTL_CONFIG=~/.flyte/config-sandbox.yaml

This will allow you to interact with your local Flyte cluster.

To interact with a Flyte cluster in the cloud you will need to adjust the configuration and point the environment variable to the new configuration file.

Alternatively, you can always specify the configuration file on the command line when invoking pyflyte or flytectl by using the --config flag. For example:

$ pyflyte --config ~/.my-config-location/my-config.yaml run my_script.py my_workflow

See Running in a local cluster for more details on the format of the yaml file.

Check your CLI configuration

To check your CLI configuration, run:

$ pyflyte info

You should get a response like this:

$ pyflyte info
╭────────────────────────────────────────────────────────── Flytekit CLI Info ──────────────────────────────────────────────────────────╮
│                                                                                                                                       │
│ This CLI is meant to be used within a virtual environment that has Flytekit installed. Ideally it is used to iterate on your Flyte    │
│ workflows and tasks.                                                                                                                  │
│                                                                                                                                       │
│ Flytekit Version: 1.15.0                                                                                                              │
│ Flyte Backend Version: <flyte-backend-version>                                                                                        │
│ Flyte Backend Endpoint: <flyte-host-url>                                                                                              │
│                                                                                                                                       │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯