Fly.io (flyctl + Machines API)
raw JSON → flyctl — see fly version update for current (auto-updates by default) verified Tue May 12 auth: yes python install: stale quickstart: stale
Fly.io is a compute platform for deploying containerized apps globally. There is no official Fly.io Python SDK — interaction is via the flyctl CLI, fly.toml config file, and the Machines REST API. The unofficial fly-python-sdk on PyPI (pip install fly-python-sdk) is a third-party project last updated October 2023 and should not be relied upon.
pip install fly-python-sdk Common errors
error flyctl: command not found ↓
cause The flyctl executable is not in your system's PATH, or the installation was incomplete.
fix
Ensure flyctl is installed correctly for your operating system (e.g., via Homebrew on macOS, or the install script which adds it to your shell's rc file). Verify your shell's PATH environment variable includes the directory where flyctl is located (e.g., ~/.fly/bin).
error Error Could not find App ↓
cause flyctl could not determine which application to operate on because the app name was not specified via the `-a` flag, the `FLY_APP` environment variable, or a `fly.toml` file in the current or parent directory.
fix
Specify the app name using
flyctl <command> -a <app_name> or ensure you are running the command in a directory containing your fly.toml file. If launching a new app, use flyctl launch. error Error: failed to fetch an image or build from source: Authentication required to access image "docker.io/<image_name>:latest" ↓
cause Flyctl or the remote builder failed to authenticate with a Docker registry (often for a private image) or the Fly.io registry itself. This can also manifest as `401 Unauthorized`.
fix
Ensure you are logged into Fly.io (
flyctl auth login) and, if using Docker images from a private registry, authenticate Docker (flyctl auth docker). Update flyctl to the latest version (flyctl version update) as older versions might have authentication issues. error Error: failed to fetch an image or build from source: error connecting to docker: failed building options: failed probing "personal": context deadline exceeded ↓
cause This often indicates a problem with WireGuard or network connectivity between your local machine (or the remote builder) and Fly.io's services, preventing image building or deployment. Another related error is `Error: ping gateway: no response from gateway received`.
fix
Run
flyctl doctor to diagnose network issues, especially WireGuard connectivity. Try flyctl wireguard reset to recreate your WireGuard peer, and if UDP is blocked, enable WebSockets with flyctl wireguard websockets enable followed by flyctl agent restart. Restarting your computer can also resolve transient network problems. error 502 Bad Gateway ↓
cause The Fly.io proxy successfully reached your machine, but your application did not respond correctly or in time. This is often caused by the app crashing, listening on the wrong port (e.g., `127.0.0.1` or `localhost` instead of `0.0.0.0`), or not being ready within the health check grace period.
fix
Check your application's logs using
flyctl logs for crashes or startup errors. Ensure your application is configured to listen on 0.0.0.0 on the internal_port specified in your fly.toml. Increase health check grace periods if your app has a slow startup. Warnings
breaking Apps V1 (Nomad-based) was fully removed March 2023. All apps migrated to V2 (Machines). Old fly.toml files using legacy [[services]] format may need updating to [http_service] for simple HTTP apps. ↓
fix Use [http_service] for single-process HTTP apps. Use [[services]] only for TCP or multi-port configurations. Run fly config validate to check.
breaking auto_stop_machines previously accepted boolean true/false. Now requires string values: 'off', 'stop', or 'suspend'. Boolean true still maps to 'stop' but causes a deprecation warning and will eventually break. ↓
fix Replace auto_stop_machines = true with auto_stop_machines = 'stop' or 'suspend'.
breaking Free tier removed for new organizations created after October 7, 2024. New accounts are pay-as-you-go only. Existing users keep legacy free allowances unless they switch plans. ↓
fix Use auto_stop_machines = 'suspend' + min_machines_running = 0 to minimize cost on low-traffic apps. Stopped/suspended machines only billed for storage (~$0.15/GB/month).
gotcha fly launch creates two Machines by default on first deploy if [http_service] is configured (redundancy by default). This doubles cost unexpectedly for hobby projects. ↓
fix Run fly scale count 1 after first deploy, or set min_machines_running = 0 with auto_stop_machines = 'suspend'.
gotcha Apps must listen on 0.0.0.0:<internal_port>, not 127.0.0.1 or localhost. Listening on localhost causes 'app is not listening on the expected address' deploy warning and the app is unreachable. ↓
fix Bind your server to 0.0.0.0. E.g. uvicorn app:app --host 0.0.0.0 --port 8080
gotcha Machine suspend (auto_stop_machines = 'suspend') requires ≤2GB RAM, no swap configured, no GPU, and no schedule. Machines not meeting requirements silently fall back to 'stop' behavior. ↓
fix Verify requirements before relying on suspend for fast cold-start. Check fly machine status <id> to confirm state transitions.
gotcha fly.toml changes do not take effect until fly deploy is run. Saving fly.toml does not trigger a redeploy. Dashboard view of fly.toml may lag behind actual deployed config. ↓
fix Always run fly deploy after any fly.toml change. Use fly config show to inspect deployed config.
gotcha flyctl auto-updates by default. New flyctl versions occasionally change behavior or add new fly.toml schema fields that conflict with old configs. Pinning flyctl version in CI is recommended. ↓
fix In GitHub Actions use superfly/flyctl-actions@v1 pinned to a specific version. Disable autoupdate in production environments with fly settings autoupdate disable.
breaking Python packages in `requirements.txt` or `pyproject.toml` may specify a minimum Python version. If the deployment environment (e.g., `fly.toml` buildpack settings, Dockerfile base image) uses an older Python version, package installation will fail with 'Requires-Python' errors. ↓
fix Ensure the Python version used in your deployment environment (e.g., specified in `fly.toml` buildpack, or your Dockerfile's `FROM` image) meets the minimum `Requires-Python` version of your dependencies. For example, if a dependency requires `Python >=3.11`, use `python:3.11-slim` or newer.
gotcha Test output shows pip warnings regarding running as the 'root' user and an available update. Running pip as root can cause permission issues, and an outdated pip might lead to unexpected behavior or missed features. ↓
fix For the 'root' user warning, ensure pip is run within a virtual environment or specify a non-root user in your Dockerfile (e.g., using a `USER` instruction). For the pip update notice, run `pip install --upgrade pip` to update pip.
Install
curl -L https://fly.io/install.sh | sh brew install flyctl Install compatibility stale last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) - - - -
3.10 slim (glibc) - - - -
3.11 alpine (musl) - - - -
3.11 slim (glibc) - - - -
3.12 alpine (musl) - - - -
3.12 slim (glibc) - - - -
3.13 alpine (musl) - - - -
3.13 slim (glibc) - - - -
3.9 alpine (musl) - - - -
3.9 slim (glibc) - - - -
Imports
- Machines API (Python) wrong
import fly fly.machines.list(app_id)correctimport requests headers = {"Authorization": f"Bearer {FLY_API_TOKEN}"} requests.get("https://api.machines.dev/v1/apps/{app_id}/machines", headers=headers)
Quickstart stale last tested: 2026-05-11
# Deploy a Python app:
# 1. In your project directory:
fly launch # Scans project, creates fly.toml, provisions app
fly deploy # Builds image, deploys to Machines
# Minimal fly.toml for a Python web app:
# app = 'my-app'
# primary_region = 'iad'
#
# [http_service]
# internal_port = 8080
# force_https = true
# auto_stop_machines = 'suspend'
# auto_start_machines = true
# min_machines_running = 0
#
# [[vm]]
# memory = '256mb'
# cpu_kind = 'shared'
# cpus = 1
# Secrets (env vars):
fly secrets set OPENAI_API_KEY=sk-...
# Scale:
fly scale count 2
fly scale memory 512