Skip to main content

​
Requirements

OpenAVM Kit requires Python 3.11 or later. The library is tested on Python 3.11 and 3.12.
Python 3.11.9 is the recommended version for maximum compatibility with all dependencies.
Check your Python version: 
python --version
If you need to install or upgrade Python, download it from the official source:
Make sure the Python executable is available in your PATH environment variable. See this PATH configuration tutorial if you need help.

​
Installation options

​
Optional dependencies

OpenAVM Kit has several optional dependency groups for specialized use cases: 
pip install jupyter

​
Jupyter notebooks

To use the included Jupyter notebooks for interactive workflows: 
pip install jupyter
jupyter notebook
The jupyter notebook command launches a local server and opens your browser to the notebook interface. Navigate to the notebooks/ directory to explore example workflows.
The Jupyter server runs locally on your machine. The browser interface communicates with this server to execute code and display results.

​
Running tests

Verify your installation by running the test suite: 
pytest
This executes all unit tests from the tests/ directory. All tests should pass on a correct installation.
Testing requires the pytest package. Install it with pip install pytest if you installed from PyPI without dev dependencies.

​
Cloud storage configuration

OpenAVM Kit supports syncing data with cloud storage providers. This is optional but useful for collaboration and backup.

​
Supported providers

  • Azure Blob Storage - Microsoft Azure cloud storage
  • HuggingFace Hub - ML model and dataset hosting
  • SFTP - Secure file transfer protocol servers

​
Setup process

1

Create credentials file

Create a .env file in the notebooks/ directory to store credentials:
# In notebooks/.env
AZURE_ACCESS=read_write
AZURE_STORAGE_CONNECTION_STRING=your_connection_string_here
Never commit .env files to version control! The repository includes a .gitignore rule to prevent this, but be careful not to override it.
2

Configure cloud settings

Create a cloud.json file in your locality data folder:
{
  "type": "azure",
  "azure_storage_container_url": "https://example.blob.core.windows.net/container"
}
For public Azure containers, set the access level to ‘Container’ (not ‘Blob’) to enable list operations.
3

Test synchronization

Use the cloud sync function in a notebook to verify connectivity:
from openavmkit.pipeline import init_notebook
from openavmkit.cloud.cloud import cloud_sync

init_notebook("your-locality-name")
cloud_sync()
Files on your local disk will be synchronized with the cloud:
  • Missing local files are downloaded
  • Missing remote files are uploaded (with write access)
  • Modified files sync based on timestamps

​
Environment variables reference

AZURE_ACCESS=read_only          # or read_write
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;...

HF_ACCESS=read_only            # or read_write
HF_REPO_ID=username/dataset-name
HF_TOKEN=hf_xxxxxxxxxxxxx

SFTP_ACCESS=read_only          # or read_write
SFTP_HOSTNAME=sftp.example.com
SFTP_PORT=22
SFTP_USERNAME=your_username
SFTP_PASSWORD=your_password

​
Troubleshooting

Ensure your virtual environment is activated and you’ve installed all dependencies:
# Verify virtual environment is active
which python  # Should show path to venv

# Reinstall dependencies
pip install -r requirements.txt
OpenAVM Kit requires specific versions of some dependencies. If you encounter conflicts:
# Create a fresh virtual environment
deactivate
rm -rf venv
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install from scratch
pip install openavmkit
If Jupyter can’t find your virtual environment:
# Install ipykernel in your venv
pip install ipykernel
python -m ipykernel install --user --name=openavmkit
Then select the “openavmkit” kernel in Jupyter.

​
Next steps

Quick start tutorial

Build your first AVM model with real data

Build docs developers (and LLMs) love

Get started for freeTalk to us