Installation¶

Storix requires Python 3.12 or newer.

Install¶

uv add storix             # local filesystem + in-memory
uv add "storix[azure]"    # + all of Azure Storage (ADLS Gen2 + Blob)
uv add "storix[s3]"       # + Amazon S3
uv add "storix[r2]"       # + Cloudflare R2
uv add "storix[minio]"    # + MinIO
uv add "storix[gcs]"      # + Google Cloud Storage
uv add "storix[cli]"      # + the sx command-line interface
uv add "storix[all]"      # all optional features

pip install storix
pip install "storix[azure]"
pip install "storix[s3]"
pip install "storix[r2]"
pip install "storix[minio]"
pip install "storix[gcs]"
pip install "storix[cli]"
pip install "storix[all]"

The base install gives you the LocalBackend (real disk) and the MemoryBackend (an in-process store, ideal for tests). Cloud backends are optional extras so you only pull in a provider SDK when you need it.

In a project you choose these up front, because your dependency file is the record. A standalone sx does not need you to: it adds and removes them on demand with sx install.

Verify¶

from storix import Storix
from storix.backends import MemoryBackend

fs = Storix(MemoryBackend())
fs.echo("it works", "/hello.txt")
print(fs.ls())                # [StorixPath('hello.txt')]
print(fs.cat("/hello.txt"))   # b'it works'

If that prints b'it works', you are ready. The MemoryBackend needs no configuration and touches nothing on disk, which makes it the quickest way to try things out.

The CLI¶

sx is a small shell over the same core. It is standalone: install it once with uv tool and it works from any directory, no project checkout or virtual environment needed.

One line¶

curl -LsSf https://storix.mghalix.com/install.sh | sh

On Windows, the same thing in PowerShell:

powershell -c "irm https://storix.mghalix.com/install.ps1 | iex"

That is the whole install. It gives you sx and the local backend.

Then pick your backends¶

Cloud backends are optional, and sx installs them itself:

sx install s3          # + S3/R2/MinIO
sx install azure,gcs   # several at once
sx uninstall gcs       # changed your mind

Doing it in this order means you decide nothing up front, and changing your mind later never sends you back to the installer's flags. Extras are cumulative: adding s3 keeps the ones you already have, and the version you are on does not move (that is sx update's job).

sx doctor tells you which are present, and naming a provider you have not installed yet tells you exactly what to run:

$ sx -p s3
sx: the s3 extra is not installed. Install it: sx install s3

See doctor, install and update for the whole set.

curl -LsSf https://storix.mghalix.com/install.sh | sh -s -- --with azure,s3
curl -LsSf https://storix.mghalix.com/install.sh | sh -s -- --all
curl -LsSf https://storix.mghalix.com/install.sh | sh -s -- --version 0.5.0
curl -LsSf https://storix.mghalix.com/install.sh | sh -s -- --help

# with options, PowerShell needs the script as a block:
& ([scriptblock]::Create((irm https://storix.mghalix.com/install.ps1))) -With azure,s3

What the script does¶

It is a thin wrapper over uv tool install: it installs one tool for your user, and it does not need root, ask for credentials, write any configuration, or edit your shell startup files. If uv is missing it says so and runs the official uv installer first. Re-running it upgrades in place.

Piping a stranger's script into a shell deserves a look first, so read it before you run it:

curl -LsSf https://storix.mghalix.com/install.sh -o install.sh
less install.sh
sh install.sh

Uninstall¶

uv tool uninstall storix

That removes sx entirely. To drop a single backend and keep the rest, use sx uninstall gcs.

With uv or pip directly¶

If you already have uv and would rather not pipe a script:

uv tool install "storix[cli]"    # sx, local backend only
uv tool install "storix[all]"    # everything, no picking

Backends go on the same way afterwards (sx install s3), so the [cli,...] combinations are only worth spelling out when you want them in one command.

Inside a project you can instead add it as a dependency:

uv add "storix[cli]"

pip install "storix[cli]"

sx --version       # print the installed version
sx                 # start the interactive shell, anchored where you ran it
sx ls /            # or run a single command
sx -p azure ls /   # point it at a configured provider

A globally installed sx discovers its configuration from three canonical files (a project storix.toml, pyproject.toml's [tool.storix], and the user file ~/.config/storix/config.toml) plus the STORIX_* environment, so it does not need a cwd-local .env. See The sx CLI for the flags, the precedence chain, and the secret policy.

If you run the launcher without the cli extra, or name a provider whose extra is missing, it exits with the exact install command instead of an optional-dependency traceback. On a uv tool install that command is sx install s3: extras can be added after the fact, without rerunning the installer. See doctor, install and update.

Tab completion, icons, transfer progress bars, and the persistent config file are covered in The sx CLI.

Next: the Quickstart.