Skip to main content

Installation

Prerequisites​

  • Python 3.11+
  • pip or uv

Install​

pip install skylos

Optional Extras​

# Core static analysis
pip install skylos

# LLM-powered agent workflows
pip install "skylos[llm]"

# Ruff Python linting through `skylos lint`
pip install "skylos[lint]"

# Ed25519 verification for `skylos verify-verdict`
pip install "skylos[verdict]"

# Dart analysis, 4.47.2 and later (builds the Dart parser from source; needs a C compiler)
pip install "skylos[dart]"

# All published optional extras
pip install "skylos[all]"

The published extras are defined in the Skylos pyproject.toml. They are llm, lint, test, verdict, dart, and all.

Dart Parser And C Compiler​

Before 4.47.2, pip install skylos also installs a Dart parser that builds from source and needs a C compiler. From 4.47.2, Dart support is the optional skylos[dart] extra. If the install fails for lack of a compiler, use the container image. Without the extra, a scan that includes .dart files reports them as not analysed instead of skipping them silently; see Language Support.

Go Engine​

Go dead-code and security checks need the native skylos-go engine. From 4.50 the PyPI wheels for Linux, macOS and Windows (x86_64 and arm64) include it, the container image includes it and the GitHub Action builds it. On other platforms skylos doctor prints the command that builds it from source, and SKYLOS_GO_BIN points Skylos at a separately built engine.

Optional Rust Acceleration​

Optional Rust acceleration can be built from source. The standard installation uses Python fallbacks. See the build guide for accelerated operations and possible differences in findings.

Container Image​

Skylos publishes a first-party multi-arch CLI image to GHCR:

docker pull ghcr.io/duriantaco/skylos:latest

Run a scan against the current repository:

docker run --rm \
-v "$PWD":/work \
-w /work \
ghcr.io/duriantaco/skylos:latest \
. --json --no-provenance

For CI, prefer a pinned release tag instead of latest.

The unqualified image uses Python 3.14. Runtime-specific tags are also published for Python 3.11 through 3.15, so container scans can match a local or CI parser exactly:

docker run --rm -v "$PWD":/work -w /work ghcr.io/duriantaco/skylos:latest-python3.15 . --json --no-provenance

Files That Cannot Be Parsed​

If a Python file cannot be parsed, Skylos names it as not analysed, marks coverage incomplete, and reports every other finding; the file is never treated as clean. The exit code is decided on the code that was analysed; --strict exits 2 instead, and so does a scan where most of the code could not be analysed. See Exit Codes And Incomplete Analysis and Exit Codes.

Initialization​

Run the init command to create a default configuration in your project root.

skylos init

This will create or append to your pyproject.toml file. Repositories without a pyproject.toml can put the same keys in skylos.toml; see Configuration.

Configuration​

Skylos uses standard pyproject.toml configuration. You can tune complexity thresholds and ignore specific rules.

[tool.skylos]
# Analysis Settings
complexity = 15 # Max Cyclomatic complexity (Default: 10)
nesting = 5 # Max indentation depth (Default: 3)
max_args = 5 # Max arguments per function
max_lines = 100 # Max lines per function
ignore = ["SKY-L002"] # List of Rule IDs to ignore

# Gatekeeper Settings (skylos --gate)
[tool.skylos.gate]
fail_on_critical = true
max_security = 0
max_quality = 10
strict = false # Set true to disable interactive bypass in CI

Verify Installation​

Run a scan on your current directory to verify everything is working.

skylos --version
skylos doctor

skylos doctor checks installation and language-engine health: it shows whether Dart support is installed and whether the Go engine is available, and prints the version-matched build command when it is not.