# 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`](https://docs.astral.sh/uv/#getting-started). > [!NOTE] Using `uv` as best practice > The `uv` tool is our [recommended package and project manager](https://docs.astral.sh/uv/). > 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: ```shell $ uv python install 3.12 ``` > [!NOTE] 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: ```shell $ uv tool install flytekit ``` This will make the `pyflyte` CLI globally available on your system. > [!NOTE] 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](https://docs.docker.com/get-docker/) 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). ## Install `flytectl` to set up a local cluster For production use you will need to install Flyte in your cloud infrastructure (see [Deployment](https://www.union.ai/docs/v1/flyte/user-guide/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. > [!NOTE] 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](https://www.union.ai/docs/v1/flyte/user-guide/api-reference/uctl-cli) for details) To install `flytectl`, follow these instructions: ### macOS To install `flytectl` on a Mac, use [Homebrew](https://brew.sh/), `curl`, or download the binary manually. **Homebrew** ```shell $ 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: ```shell $ curl -sL https://ctl.flyte.org/install | sudo bash -s -- -b /usr/local/bin ``` **Manual download** To download manually, see the [`flytectl` releases](https://github.com/flyteorg/flytectl/releases). ### Linux 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](https://jqlang.org/) needs to be installed to run this script): ```shell $ curl -sL https://ctl.flyte.org/install | sudo bash -s -- -b /usr/local/bin ``` **Manual download** To download manually, see the [`flytectl` releases](https://github.com/flyteorg/flytectl/releases). ### Windows To install `flytectl` on Windows, use `curl` , or download the binary manually. **curl** To use `curl`, in a Linux shell (such as [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)), set `BINDIR` to the install location (it defaults to `./bin`) and run the following command(note that [jq](https://jqlang.org/) needs to be installed to run this script): ```shell $ curl -sL https://ctl.flyte.org/install | sudo bash -s -- -b /usr/local/bin ``` **Manual download** To download manually, see the [`flytectl` releases](https://github.com/flyteorg/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: ```shell $ 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`. > [!NOTE] Try Flyte technology through Flyte Serverless ## Configure the connection to your cluster 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: ```shell $ 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: ```shell $ pyflyte --config ~/.my-config-location/my-config.yaml run my_script.py my_workflow ``` See [Running in a local cluster](https://www.union.ai/docs/v1/flyte/user-guide/getting-started/development-cycle/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: ```shell $ pyflyte info ``` You should get a response like this: ```shell $ 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 Endpoint: │ │ │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ``` --- **Source**: https://github.com/unionai/unionai-docs/blob/main/content/user-guide/getting-started/local-setup.md **HTML**: https://www.union.ai/docs/v1/flyte/user-guide/getting-started/local-setup/