Skip to main content

​
Installing Framefox

Get Framefox up and running on your system in just a few minutes. This guide covers system requirements, installation steps, and verification.

​
System Requirements

Python 3.12 or higher is required to run Framefox. The framework leverages modern Python features and type hints available in Python 3.12+.

​
Prerequisites

Before installing Framefox, ensure you have:
  • Python 3.12+ installed on your system
  • pip package manager (usually comes with Python)
  • A terminal or command prompt
  • (Optional) A virtual environment tool like venv or virtualenv

Check Python Version

Run python --version or python3 --version to verify you have Python 3.12 or higher installed.

Check pip

Run pip --version or pip3 --version to ensure pip is installed and working.

​
Installation Steps

1

Create a Virtual Environment (Recommended)

It’s best practice to use a virtual environment for your Python projects to avoid dependency conflicts:
# Create a new directory for your project
mkdir my-framefox-project
cd my-framefox-project

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On Linux/macOS:
source venv/bin/activate

# On Windows:
venv\Scripts\activate
You should see (venv) in your terminal prompt when the virtual environment is activated.
2

Install Framefox

Install Framefox using pip:
pip install framefox
This will install Framefox and all its dependencies, including:
  • FastAPI (version 0.115.7 or higher) - Web framework foundation
  • SQLModel (version 0.0.22 or lower) - SQL database models
  • Pydantic - Data validation
  • Uvicorn (version 0.34.0 or higher) - ASGI server
  • Jinja2 (version 3.1.4 or higher) - Template engine
  • Alembic (version 1.14.1 or higher) - Database migrations
  • Typer (version 0.15.1 or higher) - CLI framework
  • And many more supporting libraries
The installation may take a few minutes depending on your internet connection and system performance.
3

Verify Installation

Confirm that Framefox is installed correctly by checking its version:
framefox --version
You can also view available commands:
framefox --help
This should display a list of available Framefox CLI commands including:
  • framefox init - Initialize a new project
  • framefox run - Start the development server
  • framefox create - Generate components
  • framefox database - Database management
  • And more

​
Core Dependencies

Framefox automatically installs these core dependencies: 
[project]
requires-python = ">=3.12"

dependencies = [
    "fastapi>=0.115.7,<1.0.0",
    "sqlmodel<=0.0.22",
    "pydantic-settings>=2.7.1",
    "uvicorn>=0.34.0",
    "jinja2>=3.1.4",
    "typer>=0.15.1",
    "alembic>=1.14.1",
    "python-multipart<=0.0.20",
    "python-dotenv>=1.0.1",
    "passlib>=1.7.4",
    "pyjwt>=2.10.1",
    "bcrypt==4.0.1",
    "rich>=13.9.4",
    # ... and more
]

​
Database Drivers

Framefox includes drivers for multiple databases:
  • PyMySQL (>=1.1.1) - MySQL/MariaDB support
  • psycopg2-binary (>=2.9.10) - PostgreSQL support
  • SQLite - Built into Python (no additional driver needed)
You don’t need to install database drivers separately. They’re included with Framefox.

​
Optional: Database Setup

While not required for installation, you may want to set up a database:
SQLite works out of the box with no additional setup:
# No installation needed - SQLite comes with Python
Perfect for development and small applications.

​
Troubleshooting

​
Python Version Issues

If you get an error about Python version: 
# Check your Python version
python --version
python3 --version

# You may need to use python3.12 explicitly
python3.12 -m pip install framefox

​
Permission Errors

If you encounter permission errors during installation: 
# Use the --user flag
pip install --user framefox

# Or use a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Linux/macOS
pip install framefox

​
ImportError or Module Not Found

If you get import errors after installation:
  1. Ensure your virtual environment is activated
  2. Verify Framefox is installed: pip show framefox
  3. Try reinstalling: pip install --force-reinstall framefox

​
Next Steps

Now that Framefox is installed, you’re ready to create your first application!

Quickstart Guide

Follow the quickstart tutorial to build your first Framefox application in minutes.

​
Upgrading Framefox

To upgrade to the latest version of Framefox: 
pip install --upgrade framefox
To upgrade to a specific version: 
pip install framefox==0.2.0
Check the changelog before upgrading to review breaking changes and new features.

Build docs developers (and LLMs) love

Get started for freeTalk to us