Environment Setup and Usage#
This is the 6th article in the Django Ninja tutorial series.
In the previous article, we learned about the Python development tools used throughout the project.
This article guides you through setting up the example project: installing Python and Poetry, cloning the project, creating a Python Virtual Environment, and starting Django successfully.
Even if you have never used these tools before, following the guide in this article should allow you to complete the environment setup and run the project smoothly.
I have used a Mac for a long time and am less familiar with Windows, but I will do my best to provide suitable alternatives and guidance.
Alright, let's get started!
GitHub Example Project#
I. Installing Python 3.12#
Since not everyone's environment is convenient for installing pyenv (especially since it does not support Windows), here we will only discuss alternatives without pyenv.
If you want to install Python via pyenv, you can refer to the tutorial article mentioned in the previous article.
We will download and install Python 3.12 directly from the Python Official Website.
Windows Users#
- Go to the Python official download page and download the Windows installer for Python 3.12.
- Run the downloaded installer, and make sure to check the "Add Python 3.12 to PATH" option.
- After the installation is complete, open the Command Prompt and enter
python --versionto verify that the installation was successful.
macOS Users#
For macOS users, we have several ways to install Python 3.12:
- Using pyenv: This is my personally recommended method.
- Using the official installer: Download the macOS version of the installer from the Python official website and follow the instructions to install.
- Using Homebrew: If you already have Homebrew installed, you can run
brew install python@3.12in the terminal to install Python 3.12.
After installation, enter python3 --version in the command line to verify that the installation was successful.
Regardless of which method you use, please verify the Python version using the command above. As long as it is 3.12.x, it's fine.
II. Installing and Configuring Poetry#
All Python packages in the project are managed by Poetry. First, install Poetry. It can be installed directly using the official command: (The following commands apply to macOS and Linux users)
After installation, add the Poetry executable path to the system's PATH: (Zsh Users)
Bash Users:
Check if the installation was successful:
Installing and Configuring Poetry on Windows#
Windows users can refer to JetBrains' Poetry configuration tutorial, which I find very clear.
Modifying Poetry Config to Use .venv Virtual Environment#
By default, Poetry creates virtual environments under a separate directory with very long names (which is false by default).
By changing this setting to true, Poetry will create the Virtual Environment directly in the project root with the fixed name .venv.
Placing the virtual environment inside the project is my personal preference.
Alternative Solution Without Poetry#
We have prepared a requirements.txt file in the project for readers who prefer using pip. This saves the trouble of installing and configuring Poetry.
III. Downloading Project From GitHub and Creating Virtual Environment#
Next is the configuration of the project itself.
1. Clone the Project#
Here is the project link. Use the git clone command:
git clone https://github.com/kyomind/Django-Ninja-Tutorial.git
# Or
git clone git@github.com:kyomind/Django-Ninja-Tutorial.git
2. Create Virtual Environment and Install Packages#
Enter the project directory and use Poetry to create the virtual environment:
At this point, a .venv folder should be created in the project root directory, which is the project's virtual environment, currently empty.
Use poetry shell to activate the virtual environment.
Install packages using poetry install: Poetry will automatically download and install all packages required by the project according to the contents of pyproject.toml and poetry.lock.
pip Users#
pip users can create a virtual environment through the following steps: (Perform all steps in the project root directory)
- Create a virtual environment using Python's built-in venv module:
python -m venv .venv - Activate the virtual environment:
- Windows:
.venv\Scripts\activate - macOS/Linux:
source .venv/bin/activate
- Windows:
- Install packages:
pip install -r requirements.txt
IV. Initializing pre-commit#
After creating the virtual environment and running poetry install, the pre-commit package has been installed in the virtual environment.
As you can see, there is a .pre-commit-config.yaml file in the project. This file defines the check items (Git Hooks) to run before each commit.
We only need to run the following command to install the Git Hooks:
This command creates Git Hooks in the project's Git directory. It only needs to be run once per project.
V. Installing VS Code Extensions#
If your IDE is VS Code, I strongly recommend installing the Ruff and Mypy VS Code extensions. This allows you to know the current code state (whether there are issues) immediately.
In principle, both require no configuration after installation because the project already has the relevant configuration files:
- Ruff:
pyproject.toml - Mypy:
mypy.ini(merged intopyproject.tomlin the latest project updates)
In addition, since they are both CLI tools, you can also run them manually, such as running Ruff checks:
Or running Mypy checks:
But VS Code extensions are still the most convenient.
VI. Starting the Django Project#
We have completed all the necessary tool setups. Now we can start the Django server.
1. Running Database Migrations#
This is an essential step at the beginning:
In fact, the project also has a Makefile prepared, so you can also run migrations through the following command:
For the introduction and tutorial of Makefile, you can refer to Goodjack's article: Using Makefile for Web Projects: Manage Your Environment Workflow Well.
2. Starting the Development Server#
Execute the following command to start the Django development server:
Next, open the browser and visit http://127.0.0.1:8000/. You should see Django's default welcome page, indicating that the project has successfully started!
Summary#
Through the steps above, you have successfully completed the development environment configuration for the project and started the example Django project.
If you encounter problems during the setup process, you can consult the official documentation of the tools or refer to my blog tutorials. These resources can help you solve common problems or further understand their functions.
Project Branches and PRs#
During project development, we will use Git branches and GitHub PRs (Pull requests) to manage example code changes for different chapters.
This keeps the learning path clear and organized and avoids the confusion of mixing code for different features.
Note that not every article has its own branch and PR, as some chapters only involve conceptual explanations without code changes.
CodeGPT Recommendation#
Additionally, almost all commit messages in this project were automatically generated using CodeGPT developed by Bo-Yi Wu, combined with the GPT-4o mini API.
After all, even in an example project, coming up with every commit message takes effort. An automation tool makes this much more convenient while keeping the style highly consistent—perfect for a detail-oriented developer like me ☺️
Regarding CodeGPT, in addition to the introduction on the GitHub page, you can also refer to Wu's article: Talk on Generative AI CodeGPT Development Experience - ModernWeb Taipei, which shares slides.
For usage tutorials, you can refer to Will Huang's article: Introducing a Useful Tool: CodeGPT (Using GPT to Automatically Generate Git Commit Log Messages).
Now that everything is ready, let's officially enter the world of Django Ninja.