9/4/2016 organizationBestpracticefordjangoprojectworkingdirectorystructureStackOverflow

signup login tour help

Dismiss

AnnouncingStackOverflowDocumentation
WestartedwithQ&A.Technicaldocumentationisnext,andweneedyourhelp.

Whetheryou'reabeginneroranexperienceddeveloper,youcancontribute.

Signupandstarthelping LearnmoreaboutDocumentation

Bestpracticefordjangoprojectworkingdirectorystructure

Iknowthereisactuallynosinglerightway.HoweverI'vefoundthatit'shardtocreateadirectorystructurethatworkswellandremaincleanfor
everydeveloperandadministrator.Thereissomestandardstructureinmostprojectsongithub.Butitdoesnotshowawaytoorganizeanother
filesandallprojectsonpc.

Whatisthemostconvenientwaytoorganizeallthesedirectoriesondevelopmentmachine?Howdoyounamethem,andhowdoyouconnect
anddeploythistoserver?

projects(allprojectsthatyourareworkingon)
sourcefiles(theapplicationitself)
workingcopyofrepository(Iusegit)
virtualenvironment(Iprefertoplacethisneartheproject)
staticroot(forcompiledstaticfiles)
mediaroot(foruploadedmediafiles)
README
LICENSE
documents
sketches
examples(anexampleprojectthatusestheapplicationprovidedbythisproject)
database(incasesqliteisused)
anythingelsethatyouusuallyneedforsuccessfulworkonproject

TheproblemsthatIwanttosolve:

Goodnamesofdirectoriessothattheirpurposeisclear.
Keepingallprojectfiles(includingvirtualenv)inoneplace,soIcaneasilycopy,move,archive,removewholeprojectorestimatediskspace
usage.
Creatingmultiplecopiesofsomeselectedfilesetssuchasentireapplication,repositoryorvirtualenv,whilekeepingsinglecopyofanother
filesthatIdon'twanttoclone.
Deployingrightsetoffilestotheserversimplybyrsyncingselectedonedir.

django organization

editedMay1'14at14:31 askedApr3'14at15:09
raacer
944 1 10 24

4Answers

There'retwokindofDjango"projects"thatIhaveinmy ~/projects/ directory,bothhaveabit

differentstructure.:

Standalonewebsites
Pluggableapplications

Standalonewebsite
Mostlyprivateprojects,butdoesn'thavetobe.Itusuallylookslikethis:

~/projects/project_name/

http://stackoverflow.com/questions/22841764/bestpracticefordjangoprojectworkingdirectorystructure 1/6
9/4/2016 organizationBestpracticefordjangoprojectworkingdirectorystructureStackOverflow
docs/#documentation
scripts/
manage.py#installedtoPATHviasetup.py
project_name/#projectdir(theonewhichdjangoadmin.pycreates)
apps/#projectspecificapplications
accounts/#mostfrequentapp,withcustomusermodel
__init__.py
...
settings/#settingsfordifferentenvironments,seebelow
__init__.py
production.py
development.py
...

__init__.py#containsprojectversion
urls.py
wsgi.py
static/#sitespecificstaticfiles
templates/#sitespecifictemplates
tests/#sitespecifictests(mostlyinbrowserones)
tmp/#excludedfromgit
setup.py
requirements.txt
requirements_dev.txt
pytest.ini
...

Settings

Themainsettingsareproductionones.Otherfiles(eg. staging.py , development.py )simply

importeverythingfrom production.py andoverrideonlynecessaryvariables.

Foreachenvironment,thereareseparatesettingsfiles,eg.production,development.Isome
projectsIhavealsotesting(fortestrunner),staging(asacheckbeforefinaldeploy)andheroku
(fordeployingtoheroku)settings.

Requirements

Iratherspecifyrequirementsinsetup.pydirectly.Onlythoserequiredfordevelopment/test
environmentIhavein requirements_dev.txt .

Someservices(eg.heroku)requirestohave requirements.txt inrootdirectory.

setup.py

Usefulwhendeployingprojectusing setuptools .Itadds manage.py to PATH ,soIcanrun

manage.py directly(anywhere).

Projectspecificapps

Iusedtoputtheseappsinto project_name/apps/ directoryandimportthemusingrelative

imports.

Templates/static/locale/testsfiles

Iputthesetemplatesandstaticfilesintoglobaltemplates/staticdirectory,notinsideeachapp.
Thesefilesareusuallyeditedbypeople,whodoesn'tcareaboutprojectcodestructureorpython
atall.Ifyouarefullstackdeveloperworkingaloneorinasmallteam,youcancreateperapp
templates/staticdirectory.It'sreallyjustamatteroftaste.

Thesameappliesforlocale,althoughsometimesit'sconvenienttocreateseparatelocale
directory.

Testsareusuallybettertoplaceinsideeachapp,butusuallythereismanyintegration/functional
testswhichtestsmoreappsworkingtogether,soglobaltestsdirectorydoesmakesense.

Tmpdirectory

Thereistemporarydirectoryinprojectroot,excludedfromVCS.It'susedtostoremedia/static
filesandsqlitedatabaseduringdevelopment.Everythingintmpcouldbedeletedanytimewithout
anyproblems.

Virtualenv

Iprefer virtualenvwrapper andplaceallvenvsinto ~/.venvs directory,butyoucouldplaceit

inside tmp/ tokeepittogether.

Projecttemplate

I'vecreatedprojecttemplateforthissetup,djangostarttemplate

Deployment

Deploymentofthisprojectisfollowing:

source$VENV/bin/activate
exportDJANGO_SETTINGS_MODULE=project_name.settings.production
gitpull
pipinstallrrequirements.txt

#Updatedatabase,staticfiles,locales

http://stackoverflow.com/questions/22841764/bestpracticefordjangoprojectworkingdirectorystructure 2/6
9/4/2016 organizationBestpracticefordjangoprojectworkingdirectorystructureStackOverflow
manage.pysyncdbnoinput
manage.pymigrate
manage.pycollectstaticnoinput
manage.pymakemessagesa
manage.pycompilemessages

#restartwsgi
touchproject_name/wsgi.py

Youcanuse rsync insteadof git ,butstillyouneedtorunbatchofcommandstoupdateyour

environment.

Recently,Imade [djangodeploy][2] app,whichallowsmetorunsinglemanagementcommand

toupdateenvironment,butI'veuseditforoneprojectonlyandI'mstillexperimentingwithit.

Sketchesanddrafts

DraftoftemplatesIplaceinsideglobal templates/ directory.Iguessonecancreatefolder

sketches/ inprojectroot,buthaven'tusedityet.

Pluggableapplication

Theseappsareusuallypreparedtopublishasopensource.I'vetakenexamplebelowfrom
djangoforme

~/projects/djangoapp/

docs/
app/
tests/
example_project/
LICENCE
MANIFEST.in
README.md
setup.py
pytest.ini
tox.ini
.travis.yml
...

Nameofdirectoriesisclear(Ihope).Iputtestfilesoutsideappdirectory,butitreallydoesn't
matter.Itisimportanttoprovide README and setup.py ,sopackageiseasilyinstalledthrough
pip .

editedMay13'15at16:16 answeredMay5'14at9:40
perror elvard
3,130 7 27 51 1,364 1 7 11

Thankyou!Ilikeyourstructure.Itgavemeusefullideas.Goodpointsaboutusingsetup.pyforrequirements
andinstallingmanage.pyintoPATH.Couldyoupleaseshowhowyoudothelastthing?Alsogoodpoint
about'tmp'dir.I'drathernameit'local',thenImayhave'env','tmp'andanythingalsoinside.Thissolvesthe
problemofhavingtoomanydealswithgitignore.Anewproblemisthatthisnameistoocloseto'locale'.
Maybeitmakessensetomove'locale'tocoreapp'project_name',notsure.Justdontwanttochange
structurebecauseofbadname.Anysuggestions? raacer May5'14at17:05

Whenusingsetup.py,add scripts keywordargument: github.com/elvard/djangostart

template/blob/master/project/
Ilike tmp becauseitsuggests"somethingtemporary"whichcanbe

removedanytime.Toplevel locale dirisn'tnecessary,youcanplaceitanywhere.Ijustlikeittobe
consistentwithstatic/templatesdirs.elvardMay5'14at17:11

Myrequirementforabilitytomakeseveralcopiesofsourcefileswithoutcopyinganotherfilesisnotsolved
directly.Butthegoalstillmaybearchivedbyusing gitcheckout orbyexcludingjustonedir'tmp'when
cloningtheprojectdirectory.Soitseemsyourstructuremeetsallrequirements,anditisclearenoughto
useonregularbasiswithoutanydoubt.I'macceptingyouranswer.Thankyou. raacer May6'14at19:15

Thankyou.Istilldon'tunderstandwhatyoumeanby"abilitytomakeseveralcopiesofsourcefileswithout
copyinganotherfiles".Tweakedrsynccommandwoulddo,butthatisn'tprobablywhatyoumean...elvard
May7'14at20:36

Iusuallycreatedir src insideofprojectroot.Thisistheworkingcopyofsourcefilesandthegitrepository

root.Icanmakeseveralcopiesofthisdirectory src , src.bak , src_tmp andsoon.Othernonrepodirs
like env , tmp , media , backup resideonthesamelevel.SoIcanjust cprsrcsrc.bak anytimeI
wanttodosomeexperimentwithgitortocompareversionswithexternaltool.Whileyouhavelocalfiles
insideofyourrepository,Ihaverepositoryinsideofmylocalfilesdir(viceversa).Thebetternameofmy
src diris repo . raacer May8'14at1:33

Myanswerisinspiredonmyownworkingexperience,andmostlyinthebookTwoScoopsof
DjangowhichIhighlyrecommend,andwhereyoucanfindamoredetailedexplanationof
everything.Ijustwillanswersomeofthepoints,andanyimprovementorcorrectionwillbe
welcomed.Buttherealsocanbemorecorrectmanerstoachievethesamepurpose.

Projects
IhaveamainfolderinmypersonaldirectorywhereImantainalltheproyectswhereIamworking

http://stackoverflow.com/questions/22841764/bestpracticefordjangoprojectworkingdirectorystructure 3/6
9/4/2016 organizationBestpracticefordjangoprojectworkingdirectorystructureStackOverflow
on.

SourceFiles
Ipersonallyusethedjangoprojectrootasrepositoryrootofmyprojects.Butinthebookis
recommendedtoseparateboththings.Ithinkthatthisisabetterapproach,soIhopetostart
makingthechangeprogressivelyonmyprojects.

project_repository_folder/
.gitignore
Makefile
LICENSE.rst
docs/
README.rst
requirements.txt
project_folder/
manage.py
media/
app1/
app2/
...
appn/
static/
templates/
project/
__init__.py
settings/
__init__.py
base.py
dev.py
local.py
test.py
production.py
ulrs.py
wsgi.py

Repository
GitorMercurialseemtobethemostpopularversioncontrolsystemsamongDjangodevelopers.
AndthemostpopularhostingservicesforbackupsGitHubandBitbucket.

VirtualEnvironment
Iusevirtualenvandvirtualenvwrapper.Afterinstallingthesecondone,youneedtosetupyour
workingdirectory.Mineisonmy/home/envs directory,asitisrecommendedon
virtualenvwrapperinstallationguide.ButIdon'tthinkthemostimportantthingiswhereisitplaced.
Themostimportantthingwhenworkingwithvirtualenvironmentsiskeepingrequirements.txtfile
uptodate.

pipfreezel>requirements.txt

StaticRoot
Projectfolder

MediaRoot
Projectfolder

README
Repositoryroot

LICENSE
Repositoryroot

Documents
Repositoryroot.Thispythonpackagescanhelpyoumakingeasiermantainingyour
documentation:

reStructuredText
Sphinx

Sketches

Examples

Database

answeredMay1'14at10:01
cor
1,892 9 31

Thankyouforsharingyourexperience.Thereisalotof'project*'directoriesinyourstructure.Youprobably
don'tusesuchnamesinreallife,right?Let'ssaywehavea'todo'project.Howdoyounamethesedirsin
suchcase?TheproblemthatIseeinyourcurrentstructureismixingrepositorywithnonrepositoryfiles(as
younotedabove).Itmaybeannoyingtoaddanytrashto.gitignore,isnotit?Anotherdubiousthingis
keepingtheenvdirsofarfromtheprojectitself.Doesitmakesense?Whynottocreate~/docs,~/statics
andsoon?Evengitlikestositnearthesourcefiles. raacer May1'14at13:48

Iwouldnamethem:"todo_project">todo>todo(ormaybetodoapp).Ithinkthatisimportantbeeingthe
repositoryfolderintherootofthedirecectoryhierarchy.But,isjustmyopinion.Abouttheenvironment
directory,whenyouneedtosetuptheproductionenvironment,youaredonewithjusttypeing:pipinstallU
rrequirements.txt.But,asIsaid,thereisnotonesolutionforeverything.corMay1'14at15:18

Sothepathtomainappis"projects/todo_project/todo/todo".Word"projects"repeatedtwice,andword
"todo"repeatedthreetimes.Thisseemslike"projects/project/my_project/project_dir/project/project".The
namesareveryunclear.ThisisoneofmajorproblemsthatI'mtryingtosolveinmydirectorystructure.I

http://stackoverflow.com/questions/22841764/bestpracticefordjangoprojectworkingdirectorystructure 4/6
9/4/2016 organizationBestpracticefordjangoprojectworkingdirectorystructureStackOverflow
wanttonamethedirectoriestomakeiteasytounderstandthehierarchy.Whataboutrepositoryroot,could
youpleaseexplainwhyit'simportant?Alsocouldyoupleaseexplainwhatisgoodaboutkeepingenvs
outsideofmainprojectdir? raacer May2'14at14:48

Idon'tliketocreateanew settings/ directory.Isimplyaddfilesnamed settings_local.py and

settings_remote.py soIdon'thavetoeditthe BASE_DIR .Theapproachbelowincreasethe
defaultstructureinsteadofchangingit.

mysite/#Project
conf/
locale/
en_US/
fr_FR/
it_IT/
mysite/
__init__.py
settings.py#Forsomeonebase.py
settings_local.py#Forsomeonelocal.py
settings_remote.py#Forsomeoneproduction.py
urls.py
wsgi.py
static/
admin/
css/#Custombackendstyles
css/#Projectfrontendstyles
fonts/
images/
js/
sass/
staticfiles/
templates/#Projecttemplates
includes/
footer.html
header.html
index.html
myapp/#Application
core/
migrations/
__init__.py
templates/#Applicationtemplates
myapp/
index.html
static/
myapp/
js/
css/
images/
__init__.py
admin.py
apps.py
forms.py
models.py
models_foo.py
models_bar.py
views.py
templatetags/#Applicationwithcustomcontextprocessorsandtemplatetags
__init__.py
context_processors.py
templatetags/
__init__.py
templatetag_extras.py
gulpfile.js
manage.py
requirements.txt

Ithinkthis:

settings.py
settings_local.py
settings_remote.py

isbetterthanthis:

settings.py
local_settings.py
remote_settings.py

Thisconceptappliestootherfilesaswell.

Iusuallyplace node_modules/ and bower_components/ intheprojectdirectorywithinthedefault

static/ folder.

Sometimea vendor/ directoryforGitSubmodulesbutusuallyIplacetheminthe static/ folder.

editedFeb8at19:46 answeredFeb6at17:49
isar
149 9

HereiswhatIfollowonMysystem.

1. AllProjects:Thereisaprojectsdirectoryinmyhomefolderi.e. ~/projects .Allthe

http://stackoverflow.com/questions/22841764/bestpracticefordjangoprojectworkingdirectorystructure 5/6
9/4/2016 organizationBestpracticefordjangoprojectworkingdirectorystructureStackOverflow
projectsrestinsideit.
2. IndividualProject:Ifollowastandardizedstructuretemplateusedbymanydevelopers
calleddjangoskelforindividualprojects.Itbasicallytakescareofallyourstaticfileand
mediafilesandall.
3. Virtualenvironment:Ihaveavirtualenvsfolderinsidemyhometostoreallvirtual
environmentsinthesystemi.e. ~/virtualenvs .ThisgivesmeflexibilitythatIknowwhatall
virtualenvironmentsIhaveandcanlookuseeasily

Theabove3arethemainpartitionsofMyworkingenvironment.

Alltheotherpartsyoumentionedaremostlydependentonprojecttoprojectbasis(i.e.you
mightusedifferentdatabasesfordifferentprojects).Sotheyshouldresideintheirindividual
projects.

answeredMay1'14at10:32
Sahilkalra
2,360 1 9 16

Thankyou.Itmaybeannoyingtoaddanytrashto.gitignorewhenmixingrepositorywithnonrepository
files.Isnotit?Someofmyprojectshaveuptotenandmoresuchfilesanddirs,sothismakesrealproblem
forme.Anotherdubiousthingiskeepingtheenvdirsofarfromtheprojectitself.Whatistheflexibilityin
suchsolution?Whynottocreate~/docs,~/staticsandsoon?Evengitlikestositnearthesourcefiles.I
thoughtflexibilityiswhenIcanjustcopy/move/archive/removewholeprojectdirectoryincludingvirtualenv
andcanmaintainmultipleenvswithinoneprojecteasily raacer May1'14at14:04

http://stackoverflow.com/questions/22841764/bestpracticefordjangoprojectworkingdirectorystructure 6/6