smartrun 0.2.13

Run any Python script with automatic environment setup, fast package resolution via uv, and reproducible lockfile generation

smartrun

Run any Python script in a clean, disposable virtual environment — automatically.

smartrun 🚀

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

Features

• 🧪 Supports both .py and .ipynb files
• 🔍 Automatically detects and resolves imports
• 🛠️ Uses venv or fast uv environments (if available)
• 📦 Installs only what's needed, only when needed
• 💡 Reuses environments smartly to save time

---

Installation

🔹 Basic usage

pip install smartrun

This 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+

---

Usage

smartrun your_script.py

Notebook

smartrun your_notebook.ipynb

Example file that we want to run

#some_file.py
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())

Create an environment

✅ Create an environment : Windows / macOS / Linux

smartrun env .venv

✅ Activate the environment: Windows

 .venv\Scripts\activate

🐧 macOS/Linux

✅ Activate the environment: macOS/Linux

 source .venv/bin/activate

🪟 Windows

✅ Activate the environment: Windows

.venv\Scripts\activate

Tip: smartrun will automatically create and manage a virtual environment if none is activated — but you're always free to bring your own.

✅ Run the script: Windows / macOS / Linux

 smartrun some_file.py

✅ Run the jupyter file: Windows / macOS / Linux

 smartrun some_file.ipynb

Data Science Examples

🌸 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.

Why smartrun?

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.

Contributing

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.

License

BSD 3‑Clause — see LICENSE for details.

---