Requirements Files Best Practices
00:02 Now that you have a good idea about how requirements files work, and how you can leverage them to organize your Python dependencies, let’s talk about some best practices for structuring and organizing your requirements files.
00:14 When it comes to version specifiers, it’s a good idea to use exact versioning most of the time, this is also called pinning and it means that you lock down the exact version of a package that will be installed. Trust me, this will help you avoid headaches in the long run.
00:31 It’s also important that you include secondary dependencies in their exact version numbers. If you don’t include secondary dependencies and pin them down to exact versions, what can happen is that a secondary dependency gets silently upgraded on the next deploy and that might break your application.
00:48 So my recommendation here would be to use exact versions for all of your packages including secondary dependencies. Now it may make sense to go without a version specifier for some development dependencies, for example, if you’re using a third-party debugger, like ipdb or pdb++ it can make sense to leave that unpinned so that you can always work with the latest version.
Personally, I am leaning towards pinning as many packages as possible. From personal experience, I know that this can help avoid a lot of trouble. When it comes to naming your requirements files the most popular choice seems to be
requirements.txt and then also
requirements-dev.txt for those development dependencies.
Other popular choices for requirements files names, include
requirements.lock but really, this is just a naming convention and those files would function exactly the same as the
requirements.txt files you’ve seen before.
01:52 Whatever you name your file, typically they would be placed in the root folder of your project. Some projects also create a separate requirements folder, but services like Heroku typically expect that the requirements file sits in the root folder of the project so if you go with this convention, it usually makes things a little bit easier for you because you won’t have to overwrite config variables and point them to a non standard location for your requirements files.
That is why I would recommend that you always put them into the root folder of your project. One more handy feature in requirements files is that they support comments, you can see this in the example here, all you need to do is place a hash (
#) character, sort of like a Python comment, and then all text behind that is going to be ignored.
It’s a great idea to use comments in your requirements files, for example, you could use them to explain the difference between your
requirements.txt file and the
requirements-dev.txt file, this will be helpful for any developer working with the project in the future.
There is a common question around ordering dependencies inside requirements files, so should you order them, what order should you put them in, usually I start my requirements files with the direct dependencies, so these would be the dependencies that I initially installed using the
pip install command, this would include packages like Requests, or Flask, and I like to sort them alphabetically because that makes it easier to find what I am looking for.
So my typical workflow here would be to capture all dependencies using the
pip freeze command and then go through them in an editor to split them into direct dependencies and secondary dependencies and perform the ordering.
04:23 Another best practice that you already learned about is the development and production environment split. Pip allows you to link up requirements files so that when you install one, pip will go out and actually also install the other, there is a whole lesson for that in the course, so you might want to rewatch that, as it’s a highly recommended and very useful feature.
04:41 Let’s do a quick recap here, those were the requirements files best practices that you just learned, first, you learned about the importance of version pinning, second, we discussed naming schemes for requirements files, after that, you learned how to use comments in requirements files and then you learned how you can make your requirements files easier to understand by splitting the dependencies into first order and secondary dependencies.
05:04 And finally, we did a quick recap on the technique that allows you to split up your development and production dependencies. If you follow these conventions, and best practices, it will make it easier for other developers to work with your Python projects.
Become a Member to join the conversation.