flyctl

libraryflyctl — see fly version update for current (auto-updates by default)pypypi✓ verified 51d ago

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.

devops

curl -L https://fly.io/install.sh | sh

homepage ↗

Install & Compatibility

Where this runs

tested against v? · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

py 3.11

3/5 runs

py 3.12

3/5 runs

py 3.13

3/5 runs

py 3.9

✕ build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DEFAULT_API_TIMEOUT

✓ from fly_python_sdk import DEFAULT_API_TIMEOUT

✗ import requests

Primary workflow is CLI-based. fly launch detects framework and generates fly.toml. fly deploy on every code change.

# 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

flyctl --version

Debug

Known issues

breakingApps 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.

affects: V1 apps (pre-2023)

breakingauto_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'.

affects: fly.toml configs written before mid-2024

breakingFree 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).

affects: New accounts post-October 2024

gotchafly 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'.

affects: all

gotchaApps 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

affects: all

gotchaMachine 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.

affects: all

gotchafly.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.

affects: all

gotchaflyctl 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.

affects: all

breakingPython 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.

affects: all

gotchaTest 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.

affects: all

Upgrade

Version history

flyctl — see fly version update for current (auto-updates by default)latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

52 hits · last 30 days

seranking-bot

bytedance

node

ahrefsbot

amazonbot

googlebot

Resources

homepagehttps://fly.io ↗