Run any Python script in a clean, disposable virtual environment — automatically.
Run Python and Jupyter files with zero setup, zero pollution. Just run it.
smartrun scans your script or notebook, detects the required third-party packages, creates (or reuses) an isolated environment, installs what’s missing — and runs your code.
✅ No more ModuleNotFoundError
✅ No more cluttered global site-packages
✅ Just clean, reproducible execution — every time
- 🧪 Supports both
.pyand.ipynbfiles - 🔍 Automatically detects and resolves imports
- 🛠️ Uses
venvor fastuvenvironments (if available) - 📦 Installs only what's needed, only when needed
- 💡 Reuses environments smartly to save time
🔹 Basic usage
pip install smartrunThis includes support for:
- Running standard Python scripts
- Automatic environment setup
- Fast dependency resolution with uv
- Reproducible installs via pip-tools 🔹 With Jupyter notebook support If you want to run .ipynb notebook files using smartrun, install the optional jupyter dependencies:
pip install "smartrun[jupyter]"🔹 Development install (optional) For contributors and development work, install with:
pip install "smartrun[dev,jupyter]"Requires Python 3.10+
✅ Create an environment : Windows / macOS / Linux
smartrun env .venv✅ Activate the environment: Windows
.venv\Scripts\activate🐧 macOS/Linux
✅ Activate the environment: macOS/Linux ```bash source .venv/bin/activate ```🪟 Windows
✅ Activate the environment: Windows ```bash .venv\Scripts\activate ```smartrun your_script.pysmartrun your_notebook.ipynb📄 some_file.py
# smartrun: numpy>=1.24 pandas>=2.0 rich>=13.0
import numpy as np
import pandas as pd
from rich import print
df = pd.DataFrame(np.random.randn(5, 3), columns=list("ABC"))
print("Data:")
print(df, end="\n\n")
print("Column means:")
print(df.mean())
🚀 Example: Auto-Detect Imports (No Comment Needed)
Even if you don’t include any inline comment, SmartRun will:
Parse the script or notebook for import statements
Detect which are standard libraries vs third-party packages
Automatically correct package names (e.g. sklearn → scikit-learn, cv2 → opencv-python)
Install missing packages using uv (or pip fallback)
Run the file in an isolated virtual environment
No requirements.txt. No pip install. Just run the file.
✅ What SmartRun Does
Recognizes sklearn as scikit-learn
Installs numpy, pandas, and scikit-learn if not found
Runs the script safely inside a virtual environment
🧠 Bonus: Comment Overrides
You can still override versions or add constraints with an optional comment:
# smartrun: numpy>=1.24 pandas>=2.0 scikit-learn>=1.4🌸 Iris dataset analysis
# iris.py
import seaborn as sns
import pandas as pd
import matplotlib.pyplot as plt
# Load data
df = sns.load_dataset('iris')
# Show first few rows and summary
print(df.head(), end="\n\n")
print(df.describe(), end="\n\n")
# Plot pairwise relationships
sns.pairplot(df, hue='species')
plt.savefig('iris_pairplot.png')smartrun iris.py
🐼 Titanic Dataset demo
# titanic.ipynb
import pandas as pd
import seaborn as sns
import matplotlib.pyplot as plt
# Load dataset from GitHub
url = 'https://raw.githubusercontent.com/datasciencedojo/datasets/master/titanic.csv'
df = pd.read_csv(url)
# Basic stats
print(df[['Survived', 'Pclass', 'Sex']].groupby(['Pclass', 'Sex']).mean())
# Plot survival by class
sns.countplot(data=df, x='Pclass', hue='Survived')
plt.title('Survival Count by Passenger Class')
plt.savefig('titanic_survival_by_class.png')
print("Saved plot → titanic_survival_by_class.png")smartrun titanic.ipynb
If the dependencies aren’t installed yet, smartrun will fetch them automatically.
Because setup should never block you from running great code. Whether you're experimenting, prototyping, or sharing — smartrun ensures your script runs smoothly, without dependency drama.
Contributions are welcome! 🧑💻 If you’ve got ideas, bug fixes, or improvements — feel free to open an issue or a pull request. Let’s make smartrun even smarter together.