Skip to main content
This guide covers the process of building and publishing Ganimede to PyPI.

​
Build Process

1

Build the UI

First, navigate to the ui/ directory and build the production UI bundle:
cd ui
npm run build
This uses Vite to create an optimized production build in the dist/ directory. The build includes:
  • Minified JavaScript and CSS
  • Optimized assets
  • Production-ready Svelte components
2

Update version in setup.py

Before building the Python package, update the version number in setup.py.
The setup.py file contains a {{VERSION_PLACEHOLDER}} that must be replaced with the actual version number before building.
Open api/setup.py and replace the placeholder:
setup(
    name="ganimede",
    version="0.1.0",  # Replace {{VERSION_PLACEHOLDER}} with actual version
    # ... rest of configuration
)
Follow semantic versioning (MAJOR.MINOR.PATCH):
  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes
3

Build the Python package

Navigate to the api/ directory and build the distribution packages:
cd api
python3 -m build
This creates both source distribution (.tar.gz) and wheel (.whl) packages in the dist/ directory.Make sure you have the build package installed:
pip install build
4

Publish to PyPI

Upload the built packages to PyPI using twine:
python3 -m twine upload --repository pypi dist/*
You’ll be prompted for your PyPI credentials. Make sure you have:
  • A PyPI account
  • The twine package installed (pip install twine)
  • Appropriate permissions to publish the package
For testing, you can publish to TestPyPI first:
python3 -m twine upload --repository testpypi dist/*

​
Build Scripts Reference

The UI package.json includes several build-related scripts: 
"build": "vite build"
"dev": "concurrently \"vite\" \"npm run watch:tailwind\""
"start": "vite preview"
  • build: Creates production bundle
  • dev: Runs development server with hot reload
  • start: Previews production build locally
  • watch:tailwind: Watches and compiles Tailwind CSS

​
Pre-Release Checklist

Before publishing a new version:
  • Test the development build thoroughly
  • Update version in setup.py (remove {{VERSION_PLACEHOLDER}})
  • Update CHANGELOG or release notes
  • Build UI with npm run build
  • Build Python package with python3 -m build
  • Test the built package locally
  • Tag the release in Git
  • Publish to PyPI

​
Version Management

The current version must be updated in api/setup.py. The package configuration includes: 
setup(
    name="ganimede",
    version="{{VERSION_PLACEHOLDER}}",  # Update this!
    description="A Rethinking of Computational Notebooks",
    author="nottherealsanta",
    python_requires=">=3.8",
    # ... rest of configuration
)

​
Package Distribution

The built package includes:
  • Python code: All modules in ganimede/ directory
  • UI bundle: Production build from ui/dist/ → ganimede/ui_dist/
  • Entry points:
    • ganimede: Main CLI command
    • ganimede_dev: Development CLI command

​
Troubleshooting

​
Build fails

Ensure all dependencies are installed: 
pip install build twine
cd ui && npm ci

​
Upload fails

Check your PyPI credentials and network connection. You may need to configure authentication in ~/.pypirc.

​
Version conflicts

If PyPI rejects the upload due to version conflicts, ensure you’ve incremented the version number in setup.py.

Build docs developers (and LLMs) love

Get started for freeTalk to us