Table of Contents
When to Use Each Workflow
Jupyter notebooks are best when you are learning, exploring data, or iterating quickly on small experiments because you can run code in pieces and see results immediately. VS Code is best when you want an editor that supports both notebooks and regular Python files, plus strong debugging, refactoring, and project navigation. Plain scripts are best when you want repeatable runs, clean version control, and training jobs that can be launched from the command line or a server.
As a beginner, it is normal to start in notebooks and gradually move core code into scripts. A good long term pattern is to explore in a notebook, then copy stable code into a Python module, and finally run training through a script.
Jupyter Notebooks: Practical Use
In a notebook, code executes in the kernel process and state persists between cells. This is convenient, but it also means your results can depend on hidden state, such as variables defined earlier, cells run out of order, or an old version of a function still living in memory. For deep learning, this often shows up as confusing behavior when you change code but do not fully restart.
:::danger :::
Important rule, if results look inconsistent or you changed key code and something feels off, restart the kernel and run all cells from top to bottom. This is the fastest way to eliminate hidden state problems.
Use notebooks for small, readable sections. Keep imports and configuration near the top, keep data loading in one place, and avoid redefining the same functions in multiple cells. If you need to change a function repeatedly, consider moving it into a separate .py file and importing it so there is a single source of truth.
VS Code: A Productive Middle Ground
VS Code can run notebooks, edit scripts, and debug both. Install the Python extension and choose the correct interpreter so it points to the environment where PyTorch is installed. Use the integrated terminal to run the same commands you would run outside VS Code, which helps you build habits that transfer to servers and cloud machines.
The debugger is one of VS Code’s biggest advantages over notebooks. For training code, being able to set a breakpoint inside the forward pass or the training loop and inspect tensor shapes and values is often more effective than printing.
:::danger :::
Important rule, always confirm the interpreter and environment. Many “PyTorch is not found” or “CUDA not available” issues come from VS Code using a different Python environment than your terminal.
If you use notebooks inside VS Code, the same notebook state issues apply. Treat kernel restarts as a normal tool, not a last resort.
Python Scripts: Repeatable Experiments
A script is a .py file you run from the terminal, such as python train.py. Scripts encourage clean structure because everything runs from a fresh process each time. This makes your experiments easier to reproduce and your bugs easier to isolate.
A common minimal structure is to keep reusable pieces in modules and keep execution in a main entry point. You will often see a pattern like if __name__ == "__main__": so that the script can be imported without running training automatically.
:::danger :::
Important rule, guard your script entry point with if __name__ == "__main__": when writing runnable files. This prevents accidental execution when importing code from other files.
Running from the command line also makes it easy to pass configuration values, for example dataset paths or epochs. You do not need to master argument parsing yet, but you should get comfortable launching scripts from a terminal early.
Moving from Notebook to Script Without Pain
A practical workflow is to prototype in a notebook until you have a working forward pass and a basic training loop, then extract code into functions and move them into files like models.py, data.py, and train.py. Keep the notebook as a thin “driver” that imports your modules and runs a small experiment. This lets you keep interactivity while reducing the risk of notebook only bugs.
When you copy code from a notebook into a script, watch for assumptions that were previously satisfied by notebook state, such as variables defined earlier, a working directory that happens to be correct, or files referenced with relative paths that only work from one location.
Working Directory and Imports
Notebooks and scripts can run with different working directories depending on how you launch them. This affects relative file paths and local imports. Prefer explicit project structure and run from the project root when possible.
If you create local modules, make sure your project layout supports clean imports. Avoid hacks like manually editing sys.path unless you know why you are doing it, because those fixes often break when moved to another machine.
:::danger :::
Important rule, be consistent about where you run code from. Many “file not found” and “cannot import” issues are simply working directory mismatches.
Printing, Plotting, and Progress Feedback
Notebooks make plotting and quick visualization natural, which is useful while learning. Scripts typically rely on logging to the terminal or to files. While you can still plot in scripts, it is often better to save figures to disk so results are recorded even if the run happens remotely.
For long runs in scripts, add basic progress feedback, for example periodic loss prints or simple timing, so you can tell whether the run is stuck. More advanced logging tools are covered later, so for now focus on consistent, readable output.
A Simple Recommendation for Beginners
Use notebooks for learning and exploration, use VS Code as your main editor, and run training through scripts as soon as you want repeatable results. Treat notebooks as a workspace, not as the final product, and aim to have the “real” training code live in importable Python files that can be executed from a clean start.