{"id":22,"library":"flyctl","title":"Fly.io (flyctl + Machines API)","description":"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.","status":"active","version":"flyctl — see fly version update for current (auto-updates by default)","language":"python","source_language":"en","source_url":"https://fly.io/docs/","tags":["platform","deployment","containers","serverless","cli","infra","cloud"],"install":[{"cmd":"curl -L https://fly.io/install.sh | sh","lang":"bash","label":"flyctl CLI (macOS/Linux)"},{"cmd":"brew install flyctl","lang":"bash","label":"flyctl CLI (Homebrew)"},{"cmd":"pip install fly-python-sdk","lang":"bash","label":"Unofficial Python SDK (third-party, unmaintained — avoid)"}],"dependencies":[],"imports":[{"wrong":"import requests","symbol":"DEFAULT_API_TIMEOUT","correct":"from fly_python_sdk import DEFAULT_API_TIMEOUT"}],"quickstart":{"code":"# Deploy a Python app:\n# 1. In your project directory:\nfly launch          # Scans project, creates fly.toml, provisions app\nfly deploy          # Builds image, deploys to Machines\n\n# Minimal fly.toml for a Python web app:\n# app = 'my-app'\n# primary_region = 'iad'\n#\n# [http_service]\n# internal_port = 8080\n# force_https = true\n# auto_stop_machines = 'suspend'\n# auto_start_machines = true\n# min_machines_running = 0\n#\n# [[vm]]\n# memory = '256mb'\n# cpu_kind = 'shared'\n# cpus = 1\n\n# Secrets (env vars):\nfly secrets set OPENAI_API_KEY=sk-...\n\n# Scale:\nfly scale count 2\nfly scale memory 512","lang":"bash","description":"Primary workflow is CLI-based. fly launch detects framework and generates fly.toml. fly deploy on every code change."},"warnings":[{"fix":"Use [http_service] for single-process HTTP apps. Use [[services]] only for TCP or multi-port configurations. Run fly config validate to check.","message":"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.","severity":"breaking","affected_versions":"V1 apps (pre-2023)"},{"fix":"Replace auto_stop_machines = true with auto_stop_machines = 'stop' or 'suspend'.","message":"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.","severity":"breaking","affected_versions":"fly.toml configs written before mid-2024"},{"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).","message":"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.","severity":"breaking","affected_versions":"New accounts post-October 2024"},{"fix":"Run fly scale count 1 after first deploy, or set min_machines_running = 0 with auto_stop_machines = 'suspend'.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Bind your server to 0.0.0.0. E.g. uvicorn app:app --host 0.0.0.0 --port 8080","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Verify requirements before relying on suspend for fast cold-start. Check fly machine status <id> to confirm state transitions.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Always run fly deploy after any fly.toml change. Use fly config show to inspect deployed config.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"In GitHub Actions use superfly/flyctl-actions@v1 pinned to a specific version. Disable autoupdate in production environments with fly settings autoupdate disable.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"breaking","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":{"optional":[{"name":"FLY_APP_NAME","note":"Available inside running Machines. Also FLY_REGION, FLY_MACHINE_ID, FLY_ALLOC_ID."}],"required":[{"name":"FLY_API_TOKEN","note":"Required for CI/CD. Generate with: flyctl tokens create deploy -x 999999h"}]},"search_vec":"'2023':59 'api':4,35 'app':13 'cli':27,70 'cloud':72 'comput':8 'config':29 'contain':68 'container':12 'deploy':11,67 'file':30 'fli':39,47 'fly-python-sdk':38,46 'fly.io':1,5,19 'fly.toml':28 'flyctl':2,26 'global':14 'infra':71 'instal':45 'interact':22 'last':56 'machin':3,33 'octob':58 'offici':18 'parti':54 'pip':44 'platform':9,66 'project':55 'pypi':43 'python':20,40,48 'reli':64 'rest':34 'sdk':21,41,49 'serverless':69 'third':53 'third-parti':52 'unoffici':37 'updat':57 'upon':65 'via':24","created_at":"2026-03-16T04:39:09.011572+00:00","updated_at":"2026-04-16T15:10:10.061375+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"cli_name":"flyctl","cli_version":"sh: 1: flyctl: not found","type":"library","homepage":"https://fly.io","github":null,"docs":null,"changelog":null,"pypi":null,"npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-29","last_verified":"2026-06-29","next_check":"2026-07-29","install_tag":"stale"}}