Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
no_wheel
glibcpy 3.10–3.910 runs
timeout
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
vision.all
✓ from fastai.vision.all import *
Recommended for computer vision applications. The `all` module imports many common fastai components and external libraries (e.g., numpy as np, pandas as pd, matplotlib.pyplot as plt) for interactive use.
text.all
✓ from fastai.text.all import *
Recommended for natural language processing tasks, similarly providing an extensive set of imports.
tabular.all
✓ from fastai.tabular.all import *
Recommended for tabular data applications.
basics
✓ from fastai.basics import *
✗ from fastai import *
For core fastai functionality without application-specific modules. Importing `fastai` directly (as was common in v1) is deprecated in v2.
This quickstart demonstrates how to train an image classification model using fastai. It downloads the Oxford-IIIT Pet Dataset, creates `DataLoaders`, initializes a `Learner` with a pre-trained `resnet34` model, and fine-tunes it for one epoch. This showcases fastai's high-level API for rapidly achieving state-of-the-art results.
import os
from fastai.vision.all import *
# Ensure the necessary directory for models is available
# os.environ['XDG_CACHE_HOME'] = os.environ.get('XDG_CACHE_HOME', './.cache')
# Download and untar the dataset (Oxford-IIIT Pet Dataset)
path = untar_data(URLs.PETS)/'images'
# Define a function to label images (e.g., determine if an image name starts with an uppercase letter, meaning it's a cat)
def is_cat(x): return x[0].isupper()
# Create DataLoaders from image files in the specified path
# valid_pct splits data for validation, seed ensures reproducibility
# label_func applies 'is_cat' for labels, item_tfms resizes images
dls = ImageDataLoaders.from_name_func(
path, get_image_files(path), valid_pct=0.2, seed=42,
label_func=is_cat, item_tfms=Resize(224)
)
# Create a Learner with a pre-trained ResNet34 model and error_rate as a metric
learn = vision_learner(dls, resnet34, metrics=error_rate)
# Fine-tune the model for one epoch. This is a form of transfer learning.
learn.fine_tune(1)
print("Model training complete for image classification. You can now use `learn.predict(img)` for inference.")
Debug
Known issues
breakingfastai v2 is a complete rewrite and is *not API-compatible* with fastai v1. Code written for v1 will break. Key changes include data loading (`DataBunch` in v1 to `DataBlock`/`DataLoaders` in v2) and the callback API (e.g., `on_*_begin` to `before_*`).fixRefer to the fastai v2 migration guides and rewrite data loading and callback logic according to the new API. The overall architecture remains similar, making the transition less daunting than a full rewrite.
affects: All versions migrating from fastai v1 to v2+
gotchaPyTorch Version Compatibility: fastai generally requires specific PyTorch versions. While recent versions (2.8.7+) may be more lenient, historically, strict compatibility has been crucial. Installing an incompatible PyTorch version can lead to runtime errors or unexpected behavior.fixAlways check the fastai release notes or official documentation for the precise PyTorch version range supported by your installed fastai version. It is often recommended to install PyTorch first, ensuring the correct CUDA toolkit version, before installing fastai.
affects: All versions
gotchaThe heavy use of `from fastai.app_name.all import *` for convenience in interactive notebooks can lead to namespace pollution and make it difficult to trace the origin of functions and classes, potentially causing name clashes or confusion in larger projects.fixFor production code or when clarity is paramount, consider more explicit imports (e.g., `from fastai.vision.data import ImageDataLoaders`). Be aware of fastai's design philosophy, which prioritizes interactive use and rapid prototyping with `import *`.
affects: All v2+ versions
gotchaOn Windows, when running fastai code within Jupyter notebooks, `num_workers` for `DataLoader` is automatically reset to 0 to avoid multiprocessing-related hangs. This significantly slows down data loading, especially for I/O-heavy tasks like computer vision.fixFor optimal performance on Windows, it is highly recommended to use Windows Subsystem for Linux (WSL) or run fastai from a standalone Python script where `num_workers` can be utilized effectively.
affects: All v2+ versions on Windows with Jupyter
gotchaDependency conflicts with NumPy: Newer versions of NumPy (e.g., NumPy 2.0) can cause incompatibility issues with other compiled modules that fastai, or its underlying libraries, might depend on. This can result in 'procedure not found' or similar errors during runtime.fixIf encountering such errors, check fastai's and PyTorch's official documentation for compatible NumPy versions. Downgrading NumPy might be necessary, but ensure it doesn't break other critical dependencies.
affects: Potentially all versions when new NumPy releases occur
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'fastai'
This error typically occurs when fastai is not installed in the Python environment you are currently using, or if you are running your code from an environment where fastai is installed, but a different environment is active (e.g., in a Jupyter Notebook).
fixEnsure fastai is installed in your environment by running `pip install fastai` or `conda install -c fastai -c pytorch fastai`. If using Jupyter, verify that the correct conda/virtual environment with fastai installed is activated before launching Jupyter.
AttributeError: 'Learner' object has no attribute 'fine_tune'
This issue often arises due to an incorrect import statement for the `cnn_learner` or `Learner` class, or a fastai version mismatch. Fastai uses a design where certain extensions and methods are 'monkey patched' onto core classes when imported from specific 'all' modules.
fixImport all necessary components using `from fastai.vision.all import *` (or the relevant submodule like `fastai.text.all`) to ensure that all extensions, including `fine_tune`, are properly loaded onto the `Learner` object.
CUDA out of memory exception
This error indicates that your GPU does not have enough memory to process the current batch of data or to load the model. This is common in deep learning when working with large models, high-resolution images, or large batch sizes.
fixReduce the `batch_size` in your `DataLoaders`, use a smaller model architecture, decrease the input image/data size, or try freeing up GPU memory by restarting the kernel if in a notebook environment.
TypeError: code expected at most X arguments, got Y
This `TypeError` frequently occurs when loading a `fastai` model (saved using `learn.export()`) that was trained with a different version of fastai or PyTorch than the one currently installed in the inference environment. The `pickle` module, used for serialization, is sensitive to such version mismatches.
fixEnsure that the `fastai` and `PyTorch` versions in your deployment or inference environment exactly match the versions used during model training. Pinning specific versions in your `requirements.txt` file (e.g., `fastai==2.7.19`, `torch==1.13.1`) is highly recommended to avoid this.
TypeError: unsupported operand type(s) for /: 'str' and 'str'
This error occurs when attempting to construct a file path using the `/` operator with two string objects. While `fastai` and `Pathlib` allow the `/` operator for concatenating `Path` objects, it does not work directly with Python's built-in string types.
fixConvert your path components to `Path` objects from `pathlib` before using the `/` operator, or use standard string concatenation methods. For instance, instead of `path/file`, use `Path(path)/file` or `os.path.join(path, file)`.
Upgrade
Version history
2.8.8latest on PyPI · released Jul 30, 2026
Audit
Dependencies
torchrequiredfastai is built on PyTorch and requires a compatible version.
fastcorerequiredA foundational library providing essential extensions and utilities for fastai.
fastprogressrequiredUsed for progress bars during training.