Skip to content

Installation#

Required Dependencies#

  • Python (3.11 or later)
  • numpy (2.1.2 or later)
  • pandas (2.2.0 or later)
  • loguru (0.7.2 or later)

Optional, provider-specific dependencies (installed via extras):

Installation Methods#

It's recommended to install unicloud in a virtual environment to avoid conflicts with your system's Python packages.

Conda#

The easiest way to install unicloud is using the conda package manager. unicloud is available in the conda-forge channel:

conda install -c conda-forge unicloud

This installs the base package. For provider SDKs, add them explicitly:

conda install -c conda-forge boto3                 # AWS S3
conda install -c conda-forge google-cloud-storage  # GCS

PyPI#

Install the base package:

pip install unicloud

Install with provider extras:

pip install unicloud[s3]    # pulls in boto3
pip install unicloud[gcs]   # pulls in google-cloud-storage + google-api-python-client
pip install unicloud[all]   # both providers

Pin a specific version:

pip install unicloud==0.4.0

From Sources#

The sources for unicloud can be downloaded from the GitHub repository.

You can clone the public repository:

git clone https://github.com/serapeum-org/unicloud.git

Or download the tarball:

curl -OJL https://github.com/serapeum-org/unicloud/tarball/main

Once you have a copy of the source, install it with:

python -m pip install .

To install directly from GitHub (HEAD of main):

pip install git+https://github.com/serapeum-org/unicloud.git

Or a specific release:

pip install git+https://github.com/serapeum-org/unicloud.git@0.4.0

Development Installation#

If you are planning to contribute, make a git clone and do an editable install so your changes are picked up without reinstalling.

git clone https://github.com/serapeum-org/unicloud.git
cd unicloud
pip install -e ".[all]"

This project uses uv for dependency and environment management. To sync the dev environment (runtime deps + dev group + all provider extras):

uv sync --extra all --group dev

To include the docs group:

uv sync --extra all --group dev --group docs

Credentials#

AWS S3#

unicloud's S3 client reads credentials from the standard AWS environment variables:

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_DEFAULT_REGION

It also honors IAM roles (on EC2 / ECS / Lambda) and the shared credentials file written by aws configure, because those are picked up by boto3 directly. You can pass a custom botocore.config.Config via the configs argument:

from botocore.config import Config
from unicloud.aws.aws import S3

s3 = S3(configs={
    "config": Config(signature_version="s3v4"),
    "region_name": "us-west-2",
})

Google Cloud Storage#

The GCS client supports three authentication modes:

  1. Service-account JSON file path passed directly: 
    from unicloud.google_cloud.gcs import GCS
gcs = GCS("my-project", service_key_path="/path/to/service-account.json")
  2. GOOGLE_APPLICATION_CREDENTIALS environment variable pointing at a service-account JSON file: 
    gcs = GCS("my-project")
  3. SERVICE_KEY_CONTENT environment variable containing the encoded contents of a service-account JSON file — useful for CI environments where you cannot ship a file. Encode it ahead of time with unicloud.utils.encode.

Verifying the Installation#

To check that the installation is successful, run:

import unicloud
print(unicloud.__version__)

And verify the provider you care about imports:

from unicloud.aws.aws import S3            # requires `[s3]` or `[all]`
from unicloud.google_cloud.gcs import GCS   # requires `[gcs]` or `[all]`