# Welcome to fastai¶

In [ ]:
from fastai.vision import *
from fastai.gen_doc.nbdoc import *
from fastai.core import *
from fastai.basic_train import *


The fastai library simplifies training fast and accurate neural nets using modern best practices. It's based on research in to deep learning best practices undertaken at fast.ai, including "out of the box" support for vision, text, tabular, and collab (collaborative filtering) models. If you're looking for the source code, head over to the fastai repo on GitHub. For brief examples, see the examples folder; detailed examples are provided in the full documentation (see the sidebar). For example, here's how to train an MNIST model using resnet18 (from the vision example):

In [ ]:
path = untar_data(URLs.MNIST_SAMPLE)
data = ImageDataBunch.from_folder(path)
learn = cnn_learner(data, models.resnet18, metrics=accuracy)
learn.fit(1)

Total time: 00:09

epoch train_loss valid_loss accuracy
1 0.128580 0.082647 0.973503
In [ ]:
jekyll_note("""This documentation is all built from notebooks;
that means that you can try any of the code you see in any notebook yourself!
You'll find the notebooks in the <a href="https://github.com/fastai/fastai/tree/master/docs_src">docs_src</a> folder of the
<a href="https://github.com/fastai/fastai">fastai</a> repo. For instance,
<a href="https://nbviewer.jupyter.org/github/fastai/fastai/blob/master/docs_src/index.ipynb">here</a>
is the notebook source of what you're reading now.""")


## Installation and updating¶

To install or update fastai, we recommend conda:

conda install -c pytorch -c fastai fastai

For troubleshooting, and alternative installations (including pip and CPU-only options) see the fastai readme.

To get started quickly, click Applications on the sidebar, and then choose the application you're interested in. That will take you to a walk-through of training a model of that type. You can then either explore the various links from there, or dive more deeply into the various fastai modules.

We've provided below a quick summary of the key modules in this library. For details on each one, use the sidebar to find the module you're interested in. Each module includes an overview and example of how to use it, along with documentation for every class, function, and method. API documentation looks, for example, like this:

### An example function¶

In [ ]:
show_doc(rotate, full_name='rotate')


#### rotate[source][test]

rotate(degrees:uniform) → Image :: TfmAffine

Tests found for rotate:

• pytest -sv tests/test_vision_transform.py::test_deterministic_transforms [source]

To run tests please refer to this guide.

Rotate image by degrees.

Types for each parameter, and the return type, are displayed following standard Python type hint syntax. Sometimes for compound types we use type variables. Types that are defined by fastai or Pytorch link directly to more information about that type; try clicking Image in the function above for an example. The docstring for the symbol is shown immediately after the signature, along with a link to the source code for the symbol in GitHub. After the basic signature and docstring you'll find examples and additional details (not shown in this example). As you'll see at the top of the page, all symbols documented like this also appear in the table of contents.

For inherited classes and some types of decorated function, the base class or decorator type will also be shown at the end of the signature, delimited by ::. For vision.transforms, the random number generator used for data augmentation is shown instead of the type, for randomly generated parameters.

## Module structure¶

### Imports¶

fastai is designed to support both interactive computing as well as traditional software development. For interactive computing, where convenience and speed of experimentation is a priority, data scientists often prefer to grab all the symbols they need, with import *. Therefore, fastai is designed to support this approach, without compromising on maintainability and understanding.

In order to do so, the module dependencies are carefully managed (see next section), with each exporting a carefully chosen set of symbols when using import * . In general, for interactive computing, to just play around the core modules and the training loop you can do

from fastai.basics import *

If you want experiment with one of the applications such as vision, then you can do

from fastai.vision import *

That will give you all the standard external modules you'll need, in their customary namespaces (e.g. pandas as pd, numpy as np, matplotlib.pyplot as plt), plus the core fastai libraries. In addition, the main classes and functions for your application (fastai.vision, in this case), e.g. creating a DataBunch from an image folder and training a convolutional neural network (with cnn_learner), are also imported. If you don't wish to import any application, but want all the main functionality from fastai, use from fastai.basics import *. Of course, you can also just import the specific symbols that you require, without using import *.

If you wish to see where a symbol is imported from, either just type the symbol name (in a REPL such as Jupyter Notebook or IPython), or (in most editors) wave your mouse over the symbol to see the definition. For instance:

In [ ]:
Learner

Out[ ]:
fastai.basic_train.Learner

### Dependencies¶

At the base of everything are the two modules core and torch_core (we're not including the fastai. prefix when naming modules in these docs). They define the basic functions we use in the library; core only relies on general modules, whereas torch_core requires pytorch. Most type-hinting shortcuts are defined there too (at least the one that don't depend on fastai classes defined later). Nearly all modules below import torch_core.

Then, there are three modules directly on top of torch_core:

This takes care of the basics, then we regroup a model with some data in a Learner object to take care of training. More specifically:

From basic_data we can split on one of the four main applications, which each has their own module: vision, text collab, or tabular. Each of those submodules is built in the same way with:

• a submodule named transform that handles the transformations of our data (data augmentation for computer vision, numericalizing and tokenizing for text and preprocessing for tabular)
• a submodule named data that contains the class that will create datasets specific to this application and the helper functions to create DataBunch objects.
• a submodule named models that contains the models specific to this application.
• optionally, a submodule named {application}.learner that will contain Learner specific to the application.

Here is a graph of the key module dependencies: