Installation
Prerequisites
- Python 3.11+
piporuv
Install
- pip
- uv
pip install skylos
uv 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.